Zotero

Zotero

Zotero stores bibliographic metadata in personal or group libraries. Items have stable 8-character keys. Attachments and notes are child items under parent records.

Data Model

• Library — a personal library (users/{userId}) or group library (groups/{groupId}).
• Items — books, journal articles, web pages, attachments, notes, and other item types from the Zotero schema.
• Item key — 8-character identifier such as ABCD2345. Keys are stable and used in every read/write call.
• Collections — hierarchical folders within a library. Membership is stored on items via collections arrays.
• Tags — free-text labels on items. Search with the tag query parameter.
• Children — notes and file attachments linked to a parent item via parentItem.
• Versions — every item carries a numeric version. Updates and deletes must send the current version or Zotero returns 412 Precondition Failed.

Two credential field setups

Choose one setup when you connect — not both in a single credential:

Need local reads and cloud writes? Create two credentials on two MCP servers.

Cloud vs local (technical)

• Cloud Web API — user ID + API key at api.zotero.org. Full read/write.
• Local desktop API — localhost:23119 /api/… while Zotero is open. GET reads only; POST/PUT/DELETE return "Endpoint does not support method" (Zotero upstream limitation).

Common Workflows

• Search the library with keyword, tag, or item-type filters before opening individual records.
• Fetch a single item by key when you already have the identifier from search results or user input.
• List child items to reach notes and PDF attachments linked to a parent citation.
• Download attachment bytes for a child attachment item key, not the parent citation key.
• Create a new item from an item template shape, then patch metadata or add collection membership.
• Use collection tools to organize literature-review shortlists without duplicating citation records.

Operational Notes

• Item keys vs numeric IDs — always use the 8-character item key from API responses, not internal database IDs.
• Parent vs attachment — PDFs are attachment child items. Download files using the attachment item key.
• Writes need version — when updating or deleting, pass the latest version from a prior read response.
• Group libraries — pass group_id on tools that support shared group libraries.
• Local Zotero — Advanced → Allow other applications on this computer to communicate with Zotero must be enabled in Zotero settings.
• Search vs list — keyword search uses the q parameter on item reads. Do not confuse saved-search metadata with live search results.