Cite Caddy
Cite Caddy is a remote MCP server that provides full read/write access to a Zotero reference library.
Search and retrieve items, collections, tags, trash, saved searches, groups, item types, fields, and creator metadata.
Read attachments, download files as base64, and fetch extracted full text.
Read, create, and update item notes.
Export bibliographies, citations, CSL-JSON, or BibTeX for item keys.
Create, update, rename, move, and delete collections and saved searches.
Create and update items, including changing publication status and item type (e.g., preprint to journal article).
Add, remove, set, rename, and delete tags across items or library-wide.
File and unfile items into/from collections; trash and restore items.
Upload attachments and permanently delete items, collections, tags, or saved searches.
Move items between Zotero libraries (destructive: recreates under new key).
Use version checks for concurrency safety and idempotency keys for retry-safe destructive operations.
Provides full read/write access to a Zotero library, including search, add, update, delete, and move items; manage collections, tags, notes, attachments, saved searches, and trash; and retrieve Zotero item-type and field schema.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Cite Caddy Search my Zotero library for items tagged 'to-read'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Cite Caddy
A reference-library bridge for AI assistants — a standalone, remote MCP server.
Independent, unofficial project. Not affiliated with, endorsed by, or sponsored by the Corporation for Digital Scholarship (Zotero) — see Zotero's trademark policy. Built on the Zotero Web API; today's backend is Zotero, but the name and tool surface are meant to support others later.
Cite Caddy gives full read/write access to a Zotero library — search, add, tag, update, delete, and move items; create, rename, and delete collections; upload/download attachments and read their extracted full text; read and write item notes; manage tags, trash, and saved searches library-wide; and look up Zotero's own item-type/field schema. 39 tools total — see Tools below for the full list.
Why this exists
Read-only tools that match findings against a Zotero library (e.g. by DOI/arXiv ID) can safely stop at reporting — they never need to write anything back. This project goes further on purpose: full CRUD against a Zotero library, including delete and move, so that tagging, adding, and cleaning up items can be automated too.
That's a deliberate scope choice, and it comes with a real risk: any write that changes an existing item's key (delete, move to another library, "clean library" reset) breaks Word documents that cite it via the Zotero Word plugin's live field codes — see "Key safety" below before touching delete/move.
Related MCP server: zotero-mcp
Key safety (read this before implementing delete/move)
Any Zotero item cited in a Word document via the Zotero Word plugin is referenced by that item's key, embedded in a live field code. Operations that preserve an item's key (create, update fields, add/remove tags, add notes) are safe. Operations that don't (delete, and library-to-library move, which Zotero implements as delete+recreate) will break those citations silently — the Word document won't error, it'll just show stale/broken field text next time someone updates fields or opens Zotero the next time.
Full CRUD was chosen deliberately for this project despite that risk. When implementing delete/move tools:
Make the destructive intent obvious in the tool name and docstring (an MCP client's model reads both before calling), not just in this README.
Consider requiring the caller to pass back the item's current Zotero
version(optimistic concurrency) so a delete/update can't silently clobber a change made concurrently from the Zotero desktop app or another client.A dry-run / confirmation step for delete is worth considering, but is an implementation decision for whoever builds that tool, not decided here.
Idempotency
delete_item_permanently, delete_collection, delete_tag,
delete_saved_search, move_item_to_different_library, and
update_publication_status all accept an optional idempotency_key. Pass
the same opaque string when retrying a call after a lost or ambiguous
response (e.g. a network timeout) and the original outcome — success or
error — is replayed instead of running the operation against Zotero again.
Reusing a key for a call with different arguments raises an error instead of
silently returning the old result, so it's safe to generate one key per
logical request and reuse it freely on retries of that same request.
This matters most for move_item_to_different_library: it recreates the
item in the target library, then deletes it from the source. If the create
succeeds but the delete then fails, a bare retry would redo the whole thing
— since the source item's version hasn't changed — creating a second
duplicate in the target library. With idempotency_key, the retry replays
the cached failure (and its "clean up manually" guidance) instead of
touching Zotero again.
The cache is in-memory per server process (per onboarded tenant in HTTP mode), with a 24h TTL — it survives retries within that window, not across a redeploy/restart.
Configuration
stdio mode (local, single-user — no $PORT): the library to connect to
comes from env vars.
ZOTERO_LIBRARY_ID numeric library ID (user or group)
ZOTERO_LIBRARY_TYPE "user" or "group" (default: user)
ZOTERO_API_KEY from Zotero -> Settings -> Security -> Applications
(needs write permission, not just read)HTTP mode (remote, multi-tenant — $PORT set): there's no single
configured library — each caller brings their own Zotero Library ID/Type/API
Key via the /login form (see "Deployment" below). Instead:
MCP_TOKEN_STORE_KEY Fernet key encrypting onboarded tenants' API keys at
rest; generate once at deploy time with:
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
MCP_PUBLIC_URL public HTTPS URL this server is reachable at
MCP_DATA_DIR where OAuth clients/tokens/tenants persist (default: ./.data)Optional in either mode:
MCP_WEBSITE_URL public site reported as serverInfo.website_url; also used to
build serverInfo.icons[0].src as MCP_WEBSITE_URL + "icons/icon.svg"
and the /login page's privacy policy link as
MCP_WEBSITE_URL + "privacy.html" (both files must actually be
served there). Left unset, all three are simply omitted.
MCP_SECURITY_CONTACT security contact (email or URI) served as /.well-known/security.txt
(RFC 9116), e.g. for MCPBundles' ownership verification. Left
unset, that path 404s.Deployment
Ships as its own Docker container (docker-compose.yml), meant to sit
behind a reverse proxy that terminates TLS and forwards to the container's
port on localhost. Remote/hosted by default, not a local stdio server — an
MCP client just points at the URL, nothing to install or run locally.
Access is gated by a real OAuth 2.1 authorization server built into the
app itself (app/oauth_provider.py), not HTTP Basic Auth in front of it.
This is a deliberate design choice: Claude Desktop/claude.ai's "Add custom
connector" UI is OAuth-first — it always tries the OAuth discovery +
authorization-code dance against a new server, so a plain 401 in front of
the server (as Basic Auth would produce) gets read as "this server needs
OAuth" and fails once it hits a nonexistent /authorize endpoint.
Implementing a real (if minimal) OAuth server is what makes "Add custom
connector" work.
Multi-tenant and self-service: /authorize doesn't delegate to a
third-party identity provider — it shows a first-party login form asking
for a Zotero Library ID, Library Type, and API Key. Submitting the form
validates the key directly against the Zotero API; a successful
validation both grants access and registers ("onboards") that library as
a tenant of this server, all in one step — there's no separate sign-up
and no admin approval. Any MCP client can dynamically register itself
(RFC 7591), but completing the login form with a working Zotero key is
what actually gates access. Each caller's tool calls are then routed to
their own Zotero library, not a shared one. See
app/oauth_provider.py's module docstring for the full flow. Registered
clients, issued tokens, and onboarded tenants' credentials (API keys
encrypted at rest with MCP_TOKEN_STORE_KEY) persist to MCP_DATA_DIR
(a Docker volume) so redeploys don't log connected clients out or forget
onboarded tenants.
.env on the host (not in this repo) holds MCP_TOKEN_STORE_KEY/
MCP_PUBLIC_URL, consumed via docker-compose.yml's env_file:.
ZOTERO_LIBRARY_ID/ZOTERO_LIBRARY_TYPE/ZOTERO_API_KEY are not needed
for the HTTP deployment — those only apply to stdio mode.
.github/workflows/deploy.yml automates redeploying to an already
set-up host: manual trigger only (workflow_dispatch, never on push),
runs the test suite first, then syncs the repo over SSH and rebuilds the
container. It needs its own GitHub Actions secrets for the deploy SSH
key and target host/port/user — see the workflow file for the full list.
Use a dedicated deploy key (not whatever key you use for direct/manual
access), so it can be revoked independently if it ever leaks.
Monitoring
Four unauthenticated GET endpoints, HTTP mode only (all require $PORT,
same as /login):
/healthz— plain200 OK, for a load balancer/uptime check./status— JSON snapshot of aggregate, process-level activity:{ "version": "2.1.0", "uptime_seconds": 41213, "tenants": 7, "tool_calls": {"search_items": 512, "add_tags": 41}, "tool_errors": {"add_tags": 2} }tenantsisTokenStore.tenant_count()— just the number of onboarded Zotero libraries.tool_calls/tool_errorsare per-tool-name counts across all tenants combined, recorded by atools/callmiddleware (_track_tool_callinapp/mcp_server.py). Deliberately no per-tenant or per-library breakdown anywhere in this response — that's what keeps it safe to leave unauthenticated, unlike the 39 tools themselves. Counters live inapp/metrics.py, in-memory only: they reset to zero on every restart/redeploy, same as this isn't a metrics/analytics system, just a lightweight "is it up and roughly how busy is it" signal./status.html— same data as/status, rendered as a small page (name + icon, one table of version/uptime/tenants, one table of per-tool call/error counts) for a human checking in a browser rather than a script. Icon only renders whenMCP_WEBSITE_URLis set, same as/login's./.well-known/security.txt— RFC 9116 security contact, only whenMCP_SECURITY_CONTACTis set (404 otherwise).Expiresis computed per request as one year out, so it never goes stale. MCPBundles reads this to verify ownership when publishing the server to its directory./.well-known/mcp/server-card.json— a pre-connection discovery document (server identity, auth requirements, and the full tool list with schemas), generated live from the actual tool registry on every request so it can't drift out of sync. Not a ratified standard: this is a pragmatic approximation of SEP-2127 ("MCP Server Cards — HTTP Server Discovery", superseding the withdrawn SEP-1649), which is still an open, unmerged proposal as of this writing — even its own well-known path has changed between drafts (some revisions use.well-known/ai-catalog.jsoninstead) — it's not a general claim of spec compliance, and may need to change if/when SEP-2127 (or a successor) actually ratifies with a different contract.
Tools
39 tools total, grouped by risk (see "Key safety" above before using any
Destructive tool). Tools marked ✓ under Version require the
item's/collection's current Zotero version (from
search_items/get_item/list_collections) as an argument and refuse
the call if it's stale, rather than silently overwriting a concurrent
change.
Tool | Category | Version | Notes |
| Read-only |
| |
| Read-only |
| |
| Read-only | ||
| Read-only | ||
| Read-only |
| |
| Read-only | ||
| Read-only |
| |
| Read-only | ||
| Read-only | ||
| Read-only | Check before | |
| Read-only | Same, for | |
| Read-only | Name-shape fields ( | |
| Read-only | ||
| Read-only | ||
| Read-only | Content returned as | |
| Read-only | ||
| Read-only | Formatted HTML bibliography/citation entries (in a given CSL | |
| Safe write | ||
| Safe write | ||
| Safe write | ||
| Safe write | ✓ | |
| Safe write | ✓ | |
| Safe write | ✓ | Preprint → published: patches fields and, uniquely, |
| Safe write | ✓ | |
| Safe write | ✓ | |
| Safe write | ✓ | |
| Safe write | Library-wide — acts on every item carrying the tag, not just one; no per-tag version. Can block on large libraries: #6. | |
| Safe write | ✓ | |
| Safe write | ✓ | |
| Safe write | ✓ | Reversible soft delete — undo with |
| Safe write | ✓ | |
| Safe write | Content sent as | |
| Safe write | ||
| Safe write | ✓ | |
| Destructive | ✓ | Breaks Word citations. Accepts |
| Destructive | ✓ | Recreates the item under a brand-new key in the target library, then deletes the original — breaks Word citations. Accepts |
| Destructive | ✓ | Cascades to sub-collections (matching Zotero's own "Delete Collection"); never deletes the items filed in them. Accepts |
| Destructive | Library-wide — acts on every item carrying the tag, not just one; no per-tag version. Accepts | |
| Destructive | Low-risk — a saved search is just a stored filter, never touches items or citations. Accepts |
Testing
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytestTests never call a live Zotero library, even if .env has real
credentials: app/zotero_service.py (all Zotero read/write logic) is
exercised against tests/fakes.py's in-memory FakeZotero, and
app/mcp_server.py's tool functions are tested directly against a
ZoteroService backed by that fake (see configure_service()).
Status
v2.3 — deployed and in active use, with full CRUD coverage of the Zotero Web API's item/collection/tag/trash/saved-search/schema surface (39 tools; see Tools). Add it as a remote MCP connector directly (e.g. Claude Desktop/claude.ai's "Add custom connector" with just the server's public URL) — the OAuth flow described above prompts for your own Zotero Library ID/Type/API Key in-browser, no manually-configured headers needed, and no admin sign-up step.
Listed in the official MCP Registry
as dk.herbertkokholm.citecaddy/cite-caddy — metadata lives in
server.json, published via mcp-publisher and DNS-verified
against citecaddy.herbertkokholm.dk. Not (yet) part of GitHub's separate,
manually-curated github.com/mcp directory, which
doesn't sync automatically from the open registry.
Known limitations
Tracked gaps against the MCP 2026-07-28 specification
("stateless core, enterprise authorization, extensions framework"). None
are currently exploitable or user-facing — each is either inert until an
upstream mcp SDK change, or already mitigated — but are documented here
so they're visibly known rather than silently absent.
OAuth
issparam (RFC 9207) sent but not advertised. The final authorization redirect built incomplete_login()(app/oauth_provider.py) includesiss, which hardens the flow against mix-up attacks (RFC 9207 §2). The matchingauthorization_response_iss_parameter_supportedflag in/.well-known/oauth-authorization-serveris not set: that document is generated by themcpSDK, which has no setting for it as ofmcp2.3.0. Without the flag, clients don't have to validateiss, but clients that do validate it get the protection anyway.Dynamic Client Registration (RFC 7591) instead of CIMD. The same spec update formally deprecates Dynamic Client Registration in favor of Client ID Metadata Documents (CIMD), though DCR remains functional for backward compatibility. This server's client auto-provisioning (
_FlexibleClientInformation/register_client/get_clientinapp/oauth_provider.py) is built on DCR — needed because some MCP clients (observed: Claude Desktop/claude.ai) skip registration and send/authorizean unregisteredclient_iddirectly (see that class's docstring). No action needed while the installed SDK keeps DCR working without warning; will need a CIMD-based replacement if/when that changes.rename_tagcan block on large libraries — tracked as #6; candidate for the spec'stasksextension.mcp2.3.0 has a generic extension framework but no Tasks implementation yet.
Contributing
See CONTRIBUTING.md.
Security
See SECURITY.md for the threat model and how to report a vulnerability.
Privacy
See Privacy Policy for
what the server stores when you sign in at /login (Zotero Library
ID/Type/API key), how it's protected, and how to have it deleted.
License
Available Tools
39 toolsadd_tagsAIdempotentInspect
Add one or more tags to an item, keeping its existing tags. Safe, key-preserving. version: the item's current version (see update_item).
Inputs: key (required), tags (required), version (required).
add_to_collectionAIdempotentInspect
File an item into a collection, in addition to any it's already in. Safe, key-preserving reorganization within the same library -- prefer this over move_item_to_different_library whenever the goal is just organizing, not actually relocating to a different library. version: the item's current version (see update_item).
Inputs: key (required), version (required), collection_key (required).
create_collectionBInspect
Create a new collection, optionally nested under parent_key. Safe.
Inputs: name (required), parent_key.
create_itemAInspect
Add a new item to the library. Safe: creates a brand-new key, never touches an existing one.
item_type: a Zotero item type, e.g. "journalArticle", "book", "report", "webpage", "conferencePaper". fields: bibliographic fields for that type, e.g. {"title": "...", "date": "2024", "DOI": "10.1/x", "url": "...", "abstractNote": "...", "publicationTitle": "..."}. Which fields are valid depends on item_type; an invalid field raises an error naming the problem. creators: e.g. [{"creatorType": "author", "firstName": "Ada", "lastName": "Lovelace"}]. tags: plain tag strings. collections: collection keys (see list_collections) to file the new item into immediately.
Inputs: item_type (required), tags, fields, creators, +1 more.
create_noteAInspect
Add a new note as a child of an existing item (e.g. a research note attached to a journalArticle). Safe: creates a brand-new note item with its own key; never touches the parent item's own fields or version.
content: the note's body, as Zotero-flavored HTML (e.g. "Some observation.") -- Zotero derives the note's display title from the first line of this content. tags: plain tag strings.
Inputs: content (required), parent_key (required), tags.
create_saved_searchAInspect
Create a new saved search. Safe: creates a brand-new key, never touches an existing one.
conditions: a list of dicts, each with exactly the keys "condition", "operator", "value", e.g. [{"condition": "itemType", "operator": "is", "value": "journalArticle"}]. Which condition/operator combinations are valid is Zotero-defined and fairly extensive; an invalid combination raises an error naming the problem.
Inputs: name (required), conditions (required).
delete_collectionADestructiveIdempotentInspect
DESTRUCTIVE -- permanently deletes the collection. Matches Zotero's own "Delete Collection" behavior: any sub-collections nested under it are deleted too, cascading -- but items filed in it (or in a deleted sub-collection) are NOT deleted from the library, only unfiled from that collection.
There is no confirmation step at this layer; check list_collections for sub-collections first if that matters before calling this.
version: the collection's current version (from list_collections) -- the delete is refused if this doesn't match the server's current version. idempotency_key: optional opaque string; if a call with this exact key and these exact arguments already completed, that same outcome is replayed instead of running against Zotero again -- see delete_item_permanently's docstring for the full explanation.
Inputs: key (required), version (required), idempotency_key.
delete_item_permanentlyADestructiveIdempotentInspect
DESTRUCTIVE -- permanently deletes the item from its library. Cannot be undone through this server.
Any Word document citing this item via the Zotero Word plugin's live field code references it by this key; deleting it breaks that citation silently -- the document won't show an error, it'll just show stale or broken text next time someone updates fields. Only call this when that's a known, accepted consequence, not as a routine cleanup step.
version: the item's current version (from search_items/get_item) -- the delete is refused if this doesn't match the server's current version, so a concurrent edit elsewhere isn't silently discarded along with the item. idempotency_key: optional opaque string, generated once per logical request. If a call with this exact key and these exact arguments already completed -- success OR error -- that same outcome is replayed instead of deleting (or trying to delete) anything again, so retrying after a lost response can't do this twice. Reusing a key with different arguments raises an error instead of silently returning the old result.
Inputs: key (required), version (required), idempotency_key.
delete_saved_searchADestructiveIdempotentInspect
DESTRUCTIVE, but low-risk -- permanently deletes this saved search definition. Unlike delete_item_permanently/delete_collection, this doesn't touch any items or their citations -- a saved search is just a stored filter, not a container. idempotency_key: optional opaque string; if a call with this exact key already completed, that same outcome is replayed instead of running against Zotero again -- see delete_item_permanently's docstring for the full explanation.
Inputs: key (required), idempotency_key.
delete_tagADestructiveIdempotentInspect
DESTRUCTIVE -- permanently removes this tag from every item in the library that carries it (not one item -- see remove_tags for that). Cannot be undone through this server.
Unlike delete_item_permanently/delete_collection, this has no caller-supplied version to check -- Zotero's tag-delete endpoint is gated on the library's own version internally. idempotency_key: optional opaque string; if a call with this exact key and tag already completed, that same outcome is replayed instead of running against Zotero again -- see delete_item_permanently's docstring for the full explanation.
Inputs: tag (required), idempotency_key.
download_attachmentARead-onlyInspect
Download an attachment's file content (see list_attachments for
keys). Read-only. Returns content_base64 -- this server runs
remotely, so raw bytes travel as a base64 string rather than a local
file path; decode it to reconstruct the file.
Inputs: attachment_key (required).
export_bibliographyARead-onlyInspect
Generate formatted bibliography/citation entries or portable export data for one or more items. Read-only.
keys: item keys (see search_items/get_item). Keys not found in the
library are simply absent from the result -- not an error.
style: a Zotero/CSL style ID (e.g. "apa",
"modern-language-association", "chicago-note-bibliography") --
only used when format is "bibliography" or "citation"; ignored
otherwise. An unknown style raises an error naming the problem.
format:
"bibliography" (default) -- HTML reference-list entries, one per
found key, in style.
"citation" -- HTML in-text citations, one per found key, in
style.
"csljson" -- structured CSL-JSON, one object per found key --
portable, importable into other reference managers or format
converters.
"bibtex" -- one combined BibTeX text blob covering all found
keys, ready to paste into a LaTeX project.
Returns content, whose type depends on format: a list of strings
for "bibliography"/"citation", a list of objects for "csljson", or a
single string for "bibtex".
Inputs: keys (required), style, format.
get_fulltextARead-onlyInspect
Fetch Zotero's extracted full-text content and indexing progress for an attachment (see list_attachments for keys). Only meaningful for attachments Zotero has indexed -- PDFs/text files with extracted text -- not e.g. images; raises an error if there's no indexed full text for this key. Read-only.
Inputs: attachment_key (required).
get_itemARead-onlyInspect
Fetch one item by key. Read-only. Use this to get an item's current
version right before a mutating call, if you don't already have a
fresh one from search_items. creators is a list of {creatorType,
firstName, lastName} (or {creatorType, name} for single-field/
institutional creators) entries -- see search_items' docstring.
Inputs: key (required).
list_attachmentsARead-onlyInspect
List the file attachments (PDFs, snapshots, etc.) filed under an
item -- not its notes. Read-only. Each result's key can be passed to
download_attachment or get_fulltext.
Inputs: item_key (required). Returns: result
list_collectionsARead-onlyInspect
List all collections in the library (key, name, parent_collection). Read-only.
Inputs: no named parameters. Returns: result
list_creator_fieldsARead-onlyInspect
List the name-shape fields Zotero recognizes on a creators entry
(e.g. "firstName", "lastName", "name") -- for building creators
entries in create_item/update_item's creators argument. Distinct
from list_item_creator_types, which lists creatorType roles
(author, editor, ...) rather than name fields. Read-only.
Inputs: no named parameters. Returns: result
list_groupsARead-onlyInspect
List the Zotero groups the configured API key's user account
belongs to. Read-only. Each result's id can be passed as
target_library_id (with target_library_type="group") to
move_item_to_different_library, if the group you want isn't this
server's own configured library.
Inputs: no named parameters. Returns: result
list_item_creator_typesARead-onlyInspect
List the valid creatorType values (e.g. "author", "editor") for
one item type -- for create_item/update_item's creators entries,
e.g. {"creatorType": "author", ...}. Read-only.
Inputs: item_type (required). Returns: result
list_item_fieldsARead-onlyInspect
List every bibliographic field Zotero recognizes across all item types combined -- not which fields are valid for one specific type (see list_item_type_fields for that, which is what create_item actually needs). Read-only.
Inputs: no named parameters. Returns: result
list_item_type_fieldsARead-onlyInspect
List the bibliographic fields valid for one item type -- only
these keys are valid in create_item/update_item's fields argument
for this item_type; anything else raises a validation error.
Read-only.
Inputs: item_type (required). Returns: result
list_item_typesARead-onlyInspect
List every Zotero item type (e.g. "book", "journalArticle", "webpage") -- valid values for create_item's item_type argument. Read-only.
Inputs: no named parameters. Returns: result
list_notesARead-onlyInspect
List the notes filed under an item -- not its file attachments
(see list_attachments for those). Read-only. Each result includes
full note content and version -- pass both to update_note.
Inputs: item_key (required). Returns: result
list_saved_searchesARead-onlyInspect
List saved searches -- Zotero's own stored search definitions
(visible in the desktop app's left-hand pane), not ad-hoc calls to
search_items. Read-only. Each result's key can be passed to
delete_saved_search.
Inputs: no named parameters. Returns: result
list_tagsARead-onlyInspect
List distinct tags used anywhere in the library -- not one item's tags (see search_items/get_item for those). Read-only.
query: substring filter on tag name, or omit to list all tags. limit/start: pagination (default limit 100).
Inputs: limit, query, start. Returns: result
list_trashARead-onlyInspect
List items currently in the trash -- soft-deleted (e.g. via the
Zotero desktop app's "Move to Trash", or trash_item), but not yet
permanently gone. Read-only. Each result's key/version can be
passed to restore_from_trash. limit/start: pagination (default limit
25). creators shape matches search_items/get_item.
Inputs: limit, start. Returns: result
move_item_to_different_libraryADestructiveInspect
DESTRUCTIVE -- moves an item to a different Zotero library (e.g. from this user library into a group library, or vice versa). Zotero has no native cross-library move: this recreates the item in the target library under a BRAND-NEW key, then deletes the original.
Any Word citation referencing the original key is broken by this, exactly like delete_item_permanently -- silently and permanently. If the goal is just reorganizing within THIS library, use add_to_collection/remove_from_collection instead -- those preserve the key and citations keep working.
target_library_id/target_library_type: the destination library; the configured ZOTERO_API_KEY must have write access to it. version: the item's current version in the source library (from search_items/get_item) -- refused if stale. idempotency_key: strongly recommended for this tool specifically. If the create-in-target step succeeds but the delete-from-source step then fails, this operation ends up erroring while the item now exists in BOTH libraries -- a bare retry would redo the whole thing and create a SECOND duplicate in the target library, since the source item's version hasn't changed. Passing the same idempotency_key on retry replays the original failure (and its "clean up manually" guidance) instead of touching Zotero again. Also protects the normal success path the same way delete_item_permanently's does.
Returns old_key and new_key -- report both to the caller so anyone relying on the old key knows it changed.
Inputs: key (required), version (required), target_library_id (required), target_library_type (required), +1 more.
remove_from_collectionAIdempotentInspect
Remove an item from one collection; it stays in the library and any other collections it's filed under. Safe, key-preserving. version: the item's current version (see update_item).
Inputs: key (required), version (required), collection_key (required).
remove_tagsAIdempotentInspect
Remove one or more tags from an item; other tags are kept. Safe, key-preserving. version: the item's current version (see update_item).
Inputs: key (required), tags (required), version (required).
rename_tagAIdempotentInspect
Rename a tag across every item in the library that carries it (not just one item -- see add_tags/remove_tags/set_tags for single-item edits). Zotero has no native tag-rename: this adds new_tag and removes old_tag on each affected item individually, merging with each item's existing tags.
Not atomic across items -- if it fails partway through (e.g. a concurrent edit on one item), re-run with the same arguments; already-renamed items are skipped since they no longer carry old_tag.
Inputs: new_tag (required), old_tag (required).
restore_from_trashAIdempotentInspect
Remove an item from the trash, restoring it to the library. Safe, key-preserving. version: the item's current version (from list_trash).
Inputs: key (required), version (required).
search_itemsARead-onlyInspect
Search the Zotero library. Read-only.
query: substring match against title/creator/year (Zotero's quick
search), or omit to list items.
item_type: filter to one Zotero item type, e.g. "journalArticle",
"book", "report", "webpage".
tag: filter to items carrying this exact tag.
collection_key: filter to items filed in this collection (see
list_collections).
limit/start: pagination (default limit 25).
full_text: also match query against the indexed content of attached
files and notes, not just title/creator/year (Zotero's
qmode="everything"). Slower than the default search. Requires a
non-empty query -- raises a validation error otherwise.
Each result includes key and version -- pass both to update_item,
add_tags/remove_tags/set_tags, add_to_collection/remove_from_collection,
delete_item_permanently, or move_item_to_different_library. creators
is a list of {creatorType, firstName, lastName} (or {creatorType,
name} for single-field/institutional creators) entries, preserving
each creator's role (author, editor, seriesEditor, translator,
contributor, ...) -- the same shape create_item/update_item accept,
so it can be passed straight back in.
Inputs: tag, limit, query, start, +3 more. Returns: result
set_tagsAIdempotentInspect
Replace ALL of an item's tags with exactly this list (not merged -- use add_tags/remove_tags to change tags incrementally instead). Safe, key-preserving. version: the item's current version (see update_item).
Inputs: key (required), tags (required), version (required).
trash_itemADestructiveIdempotentInspect
Move an item to the trash (soft delete). Unlike delete_item_permanently, this is reversible via restore_from_trash -- prefer it whenever a delete might need to be undone. Safe, key-preserving: the item's key is unchanged, so a Word citation referencing it keeps resolving unless/until it's later permanently deleted (e.g. via delete_item_permanently, or "Empty Trash" in the Zotero desktop app).
version: the item's current version (from search_items/get_item) -- refused if stale, same as update_item.
Inputs: key (required), version (required).
update_collectionAIdempotentInspect
Rename and/or move (reparent) a collection, in place. Safe: the collection's key is unchanged, so items filed in it and any sub-collections stay put.
name: new name; omit to leave the current name unchanged. parent_key: new parent collection's key, to nest this collection under it; pass "" (empty string) to move it to the top level (out of any parent); omit entirely to leave the parent unchanged. At least one of name/parent_key must be given. version: the collection's current version (from list_collections) -- refused if stale, same as update_item.
Inputs: key (required), version (required), name, parent_key.
update_itemAIdempotentInspect
Edit bibliographic fields (title, date, DOI, url, abstractNote,
publicationTitle, creators, etc.) on an existing item, in place. Safe:
the item's key is unchanged, so any Word citation referencing it keeps
working. creators (if included) replaces the whole author/editor
list -- e.g. [{"creatorType": "author", "firstName": "Ada",
"lastName": "Lovelace"}], not a merge into the existing list.
version: the item's current version (from search_items/get_item) -- the edit is refused if this doesn't match the server's current version (someone else changed the item since you read it; re-fetch and retry). fields may NOT include tags/collections -- use add_tags/remove_tags/ set_tags and add_to_collection/remove_from_collection for those.
Inputs: key (required), fields (required), version (required).
update_noteAIdempotentInspect
Edit a note's content, in place. Safe, key-preserving. version: the note's current version (from list_notes).
Inputs: key (required), content (required), version (required).
update_publication_statusAIdempotentInspect
Update an item in place to reflect that a preprint has been formally published -- e.g. an arXiv preprint that just received a journal DOI. Same key-preserving patch as update_item (Word citations keep working) -- prefer this or update_item over deleting and recreating the item whenever a preprint's status changes.
Unlike update_item, item_type may also be passed to change the
item's Zotero type (e.g. "preprint" -> "journalArticle") --
update_item forbids that because it changes which fields are valid;
this is the one tool where that's the deliberate point of the call.
fields: same rules as update_item -- bibliographic fields such as DOI, url, date, publicationTitle, volume, issue, pages. May NOT include tags/collections/itemType/key/version -- use the dedicated tools for tags/collections, and item_type (not fields["itemType"]) to change the item type. item_type: new Zotero item type (see list_item_types); omit to leave it unchanged. version: the item's current version (from search_items/get_item) -- refused if stale, same as update_item. idempotency_key: an opaque string you generate once per logical request. If a call with this exact key and these exact arguments already completed -- success OR error -- that same outcome is replayed instead of running anything against Zotero again, so retrying after a lost response (e.g. a timeout) can't turn one edit into two. Reusing a key with DIFFERENT arguments raises an error instead of silently returning the old result -- use a fresh key per distinct request.
Inputs: key (required), fields (required), version (required), item_type, +1 more.
upload_attachmentAInspect
Upload a new file attachment as a child of an existing item (e.g. attach a PDF to a journalArticle item). Safe: creates a brand-new attachment item with its own key; never touches the parent item's own fields or version.
filename: name to store the file under, e.g. "paper.pdf" -- also used to guess Zotero's contentType from the extension. content_base64: the file's bytes, base64-encoded. This server runs remotely and has no access to the caller's local filesystem, so content must travel as a string rather than a local path. title: attachment title shown in Zotero; defaults to filename.
Inputs: filename (required), parent_key (required), content_base64 (required), title.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 39 tools
Most tools are clearly separated, aided by exceptionally thorough descriptions that cross-reference sibling tools (e.g., add_tags/remove_tags/set_tags vs rename_tag; download_attachment vs get_fulltext; trash_item vs delete_item_permanently). The main ambiguity risk is the cluster of metadata-discovery tools—list_item_fields, list_item_type_fields, list_item_creator_types, list_creator_fields—whose subtle boundaries could cause misselection, and the update_item/update_publication_status pair where one is a special case of the other.
The set consistently follows snake_case verb_noun conventions: list_* for reads, create_*/update_*/delete_* for lifecycle operations, and add_*/remove_*/set_* for granular edits. Minor deviations include upload_attachment (which breaks the create_* pattern used by create_note/create_item), the asymmetric restore_from_trash vs trash_item pair, and the verbose move_item_to_different_library.
At 39 tools, the surface is well beyond the 25+ threshold, even though Zotero's domain is genuinely complex. The count is inflated by five metadata-listing tools (list_item_types, list_item_fields, list_item_type_fields, list_item_creator_types, list_creator_fields) and five tag-related tools that could plausibly be consolidated into fewer, more general introspection and tag-management tools.
Lifecycle coverage is strong: items have full CRUD plus trash/restore/permanent-delete and cross-library move; collections, notes, attachments, and tags all have appropriate creation, mutation, and deletion paths. The notable gap is saved searches, which have create/list/delete but no update tool, forcing delete-and-recreate workflows; attachment metadata updates also lack a dedicated tool, though update_item likely covers them since attachments are items.
Maintenance
Related MCP Connectors
Zotero MCP server for Claude and ChatGPT: search, citations, safe writes, PDF passages and pages.
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Related MCP Servers
- FlicenseNot gradedqualityAmaintenanceEnables AI assistants to search a Zotero library, retrieve item metadata, and access full-text PDF contents through MCP tools.-
- FlicenseNot gradedqualityAmaintenanceEnables AI assistants to search a Zotero library, retrieve item metadata, and access full-text PDF contents through MCP tools.-
- FlicenseNot gradedqualityAmaintenanceEnables AI assistants to search a Zotero library, retrieve complete item metadata, and access full-text content such as PDFs through MCP tools.-
- FlicenseNot gradedqualityAmaintenanceEnables AI assistants and MCP clients to search a Zotero library, retrieve item metadata, and access full-text/PDF contents through the Zotero API.-