Zotero Skill

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

Setup

Requires two environment variables:

CODEBLOCK0

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):

CODEBLOCK1

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).

CODEBLOCK2

Commands

Global Flags

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

Common Options

• - --limit N — Max items to return (default 25)
• INLINECODE39 — Sort by dateModified, title, creator, date
• INLINECODE40 — Sort direction
• INLINECODE41 — Filter by or add to collection
• INLINECODE42 — Filter by item type (journalArticle, book, conferencePaper, etc.)
• INLINECODE43 — Add tags when creating items
• INLINECODE44 — Skip duplicate detection on add commands

Workflows

Add a paper by DOI

CODEBLOCK3

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

Bulk add from a file

CODEBLOCK4

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

Export bibliography

CODEBLOCK5

Update tags/metadata

CODEBLOCK6

Delete items

CODEBLOCK7

Cross-reference citations

CODEBLOCK8

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

Find missing DOIs

CODEBLOCK9

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

CODEBLOCK10

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

CODEBLOCK11

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.
• INLINECODE54 fetches all items; for large libraries (500+), this may be slow
• INLINECODE55 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