| name | zotero-research-library |
| description | Work with a Zotero research library for paper-reading workflows: search local items, inspect metadata, read attached PDFs, export notes/highlights/annotations, summarize a user's reading state, create child notes via Zotero Web API when explicitly requested, and troubleshoot Zotero Connector/API issues. Use when the user asks Codex to interact with Zotero, read Zotero annotations, make reading digests, manage paper notes/tags/attachments, or investigate whether agent-assisted Zotero edits are possible. |
Zotero Research Library
Operating Rules
- Prefer read-only local access first. Use Zotero Local API if enabled, or open
zotero.sqlite with mode=ro&immutable=1.
- Never write directly to
zotero.sqlite while Zotero is running. Treat direct SQLite writes as a last-resort experiment requiring explicit user approval, a backup, and Zotero closed.
- For edits, prefer official Zotero Web API writes with an API key. Local API is currently GET-only.
- For native PDF highlights/annotations, prefer Zotero UI or a Zotero-side bridge/plugin/MCP. Do not promise reliable native annotation creation via local API or SQLite alone.
- Preserve provenance: include Zotero item key, itemID, attachment key, page labels, colors, comments, DOI/URL, and local attachment path in digests.
Tool Selection
Use this skill as the default for lightweight paper-reading work:
- inspect papers already in Zotero
- export notes/highlights/annotations into a digest
- answer questions about the user's reading state
- create a child note only after an explicit write request
Reach for a community tool instead when the request exceeds this skill's scope:
54yyyu/zotero-mcp: best broad MCP choice for semantic search, full-text indexing, native annotation access, DOI import, collections, and hybrid local-read/web-write workflows.cli-anything-zotero: strongest local-write option when a Zotero JS Bridge plugin is acceptable and the user wants local write operations without a Zotero Web API key.llm-for-zotero: best in-reader experience when the user wants LLM help inside Zotero while reading PDFs.WenyuChiou/zotero-skills or c0mm4nd/zotero-skills: better than this skill for full Web API CRUD over items, notes, collections, tags, and attachments.drguptavivek/zotero-use: useful for writing workflows that involve Zotero references and Word .docx citation fields.ketthub/zotero-skill: useful as a minimal read-only search implementation; this skill already covers a similar local-read niche but with annotation digest support.
Quick Start
Use the bundled read-only helper for local inspection:
python3 "$CODEX_HOME/skills/zotero-research-library/scripts/zotero_read.py" --db "$HOME/Zotero/zotero.sqlite" search "SABER"
python3 "$CODEX_HOME/skills/zotero-research-library/scripts/zotero_read.py" --db "$HOME/Zotero/zotero.sqlite" digest --item-key ITEMKEY --output reading-digest.md
On a remote Mac, run through SSH:
ssh sourya-mac 'python3 /path/to/zotero_read.py --db "$HOME/Zotero/zotero.sqlite" digest --item-key ITEMKEY'
Use the Web API note helper only when the user explicitly wants a Zotero note written:
ZOTERO_API_KEY=... ZOTERO_USER_ID=... \
python3 "$CODEX_HOME/skills/zotero-research-library/scripts/zotero_web_note.py" \
--parent ITEMKEY --title "Codex reading synthesis" --markdown notes.md
Dry-run is the default. Add --execute only after confirming the target item and note body.
Common Workflows
Inspect a paper the user is reading
- Search by title/DOI/arXiv ID with
zotero_read.py search.
- Identify the clean parent item, not stale webpage or troubleshooting items.
- Run
zotero_read.py digest --item-key ....
- Read the digest plus, if needed, extract the attached PDF text with the
pdf skill.
- Summarize the user's highlights and answer their margin questions.
Create a reading digest
Include:
- metadata: title, creators, year, DOI, URL, item key
- child notes
- attachments and local paths
- annotation count by color
- annotations ordered by attachment sort/page order
- comments separately from selected text
- an interpretation section only after raw evidence is captured
Add or update notes
- Use Zotero Web API writes with a key that has write access.
- Prefer creating a new child note over editing an existing note unless the user asks to modify a specific note.
- Use
--dry-run first and show the target parent key/title.
- Remind the user that Zotero desktop may need sync before Web API changes appear locally.
Annotation/highlight edits
- Reading existing annotations is safe via local DB/Local API/Web API.
- Creating native PDF annotations is not reliably supported by Zotero Local API alone. Web API exposes annotations as child items, but local GET-only API cannot create them, and direct DB insertion may not appear in the reader due to runtime/cache internals.
- If native annotation creation is important, consider installing a Zotero MCP/plugin/JS bridge. See
references/web-findings.md.
- A safe alternative is to create a child note with quoted passages and page labels, then ask the user to apply highlights manually in Zotero.
Resources
scripts/zotero_read.py: read-only local SQLite search/detail/digest exporter.scripts/zotero_web_note.py: explicit Web API child-note creation helper with dry-run default.references/web-findings.md: current API/MCP findings and constraints.
