Source Code

Zotero Skill

Interact with Zotero personal or group libraries via the REST API v3.

Setup

Requires two environment variables:

ZOTERO_API_KEY   — Create at https://www.zotero.org/settings/keys/new
ZOTERO_USER_ID   — Found on the same page (numeric, not username)

For group libraries, set ZOTERO_GROUP_ID instead of ZOTERO_USER_ID.

Optional env var for CrossRef/Unpaywall polite pool (improves DOI lookup success rate):

CROSSREF_EMAIL   — Your email (optional; uses fallback if unset)

If credentials are missing, tell the user what's needed and link them to the key creation page.

CLI Script

All operations use scripts/zotero.py (Python 3, zero external dependencies).

python3 scripts/zotero.py <command> [options]

Commands

Command	Description	Example
`items`	List top-level items	`zotero.py items --limit 50`
`search`	Search by query	`zotero.py search "cognitive load"`
`get`	Full item details + attachments	`zotero.py get ITEMKEY`
`collections`	List all collections	`zotero.py collections`
`tags`	List all tags	`zotero.py tags`
`children`	List attachments/notes for item	`zotero.py children ITEMKEY`
`add-doi`	Add item by DOI (dedup enabled)	`zotero.py add-doi 10.1234/example`
`add-isbn`	Add item by ISBN (dedup enabled)	`zotero.py add-isbn 978-0-123456-78-9`
`add-pmid`	Add item by PubMed ID	`zotero.py add-pmid 12345678`
`delete`	Move items to trash (recoverable by default)	`zotero.py delete KEY1 KEY2 --yes`
`update`	Modify item metadata/tags	`zotero.py update KEY --add-tags "new"`
`export`	Export as BibTeX/RIS/CSL-JSON	`zotero.py export --format bibtex`
`batch-add`	Add multiple items from file	`zotero.py batch-add dois.txt --type doi`
`check-pdfs`	Report which items have/lack PDFs	`zotero.py check-pdfs`
`crossref`	Match citations vs library	`zotero.py crossref bibliography.txt`
`find-dois`	Find & add missing DOIs via CrossRef	`zotero.py find-dois --limit 10`
`fetch-pdfs`	Fetch open-access PDFs for items	`zotero.py fetch-pdfs --dry-run`

Global Flags

--json — JSON output instead of human-readable (works with items, search, get)

Common Options

--limit N — Max items to return (default 25)
--sort FIELD — Sort by dateModified, title, creator, date
--direction asc|desc — Sort direction
--collection KEY — Filter by or add to collection
--type TYPE — Filter by item type (journalArticle, book, conferencePaper, etc.)
--tags "tag1,tag2" — Add tags when creating items
--force — Skip duplicate detection on add commands

Workflows

Add a paper by DOI

python3 zotero.py add-doi "10.1093/jamia/ocaa037" --tags "review"
# Warns if already in library. Use --force to override.

Duplicate detection: translates DOI to metadata, searches library by first author, compares DOI fields.

Bulk add from a file

# One identifier per line, # for comments
python3 zotero.py batch-add dois.txt --type doi --tags "imported"

Skips duplicates. Reports summary: added/skipped/failed.

Export bibliography

python3 zotero.py export --format bibtex --output refs.bib
python3 zotero.py export --format csljson --collection COLLKEY

Update tags/metadata

python3 zotero.py update ITEMKEY --add-tags "important" --remove-tags "unread"
python3 zotero.py update ITEMKEY --title "Corrected Title" --date "2024"
python3 zotero.py update ITEMKEY --doi "10.1234/example"
python3 zotero.py update ITEMKEY --url "https://example.com/paper"
python3 zotero.py update ITEMKEY --add-collection COLLKEY

Delete items

python3 zotero.py delete KEY1 KEY2 --yes           # Trash (recoverable, default)
python3 zotero.py delete KEY1 --permanent --yes    # Permanent delete

Cross-reference citations

python3 zotero.py crossref my-paper.txt

Extracts Author (Year) patterns from text and matches against library.

Find missing DOIs

# Dry run (default) — show matches without writing anything
python3 zotero.py find-dois --limit 20

# Actually write DOIs to Zotero
python3 zotero.py find-dois --apply

# Filter by collection
python3 zotero.py find-dois --collection COLLKEY --apply

Scans journalArticle and conferencePaper items missing DOIs, queries CrossRef, and matches by title similarity (>85%), exact year, and first author last name. Dry run by default — use --apply to write. Only patches the DOI field; never touches other metadata. 1s delay between CrossRef requests (polite pool with mailto).

Fetch open-access PDFs

# Dry run — show which PDFs are available and from where
python3 zotero.py fetch-pdfs --dry-run --limit 10

# Fetch and attach as linked URLs (no storage quota used)
python3 zotero.py fetch-pdfs --limit 20

# Also save PDFs locally
python3 zotero.py fetch-pdfs --download-dir ./pdfs

# Upload to Zotero storage instead of linked URL
python3 zotero.py fetch-pdfs --upload --limit 10

# Only try specific sources
python3 zotero.py fetch-pdfs --sources unpaywall,semanticscholar

Tries three legal OA sources in order: Unpaywall → Semantic Scholar → DOI content negotiation. By default creates linked URL attachments (no Zotero storage quota needed). Use --upload for full S3 upload to Zotero storage. Use --download-dir to also save PDFs locally.

Sources: unpaywall, semanticscholar, doi (default: all three)

Rate limits: 1s between Unpaywall/Semantic Scholar requests, 2s between DOI requests.

Scripting with JSON

python3 zotero.py --json items --limit 100 | jq '.items[].DOI'
python3 zotero.py --json get ITEMKEY | jq '.title'

Notes

Zero dependencies — Python 3 stdlib only (urllib, json, argparse)
Write operations require an API key with write permissions
If Zotero translation server is down (503), DOI lookups fall back to CrossRef
Input validation: DOIs must be 10.xxxx/... format. Item keys are 8-char alphanumeric (e.g., VNPN6FHT). ISBNs must be valid checksums.
check-pdfs fetches all items; for large libraries (500+), this may be slow
fetch-pdfs also processes all items — use --collection to scope for large libraries
Rate limits are generous; batch-add includes 1s delay between items
For common errors and troubleshooting, see references/troubleshooting.md