Skip to main content
Glama

Cite Caddy

cite-caddy MCP server MCP Registry MCPBundles Lint Latest release License: MIT

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 — plain 200 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}
    }

    tenants is TokenStore.tenant_count() — just the number of onboarded Zotero libraries. tool_calls/tool_errors are per-tool-name counts across all tenants combined, recorded by a tools/call middleware (_track_tool_call in app/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 in app/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 when MCP_WEBSITE_URL is set, same as /login's.

  • /.well-known/security.txt — RFC 9116 security contact, only when MCP_SECURITY_CONTACT is set (404 otherwise). Expires is 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.json instead) — 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

search_items

Read-only

query defaults to Zotero's quick search (title/creator/year); full_text=True also matches indexed content of attached files/notes (qmode="everything"), requires non-empty query. Each result's creators is a list of {creatorType, firstName, lastName} (or {creatorType, name} for single-field/institutional creators) entries — same shape create_item/update_item accept, preserving role (author vs. editor vs. translator, ...).

get_item

Read-only

creators shape as above.

list_collections

Read-only

list_tags

Read-only

list_trash

Read-only

creators shape as above.

list_saved_searches

Read-only

list_groups

Read-only

id doubles as target_library_id (with target_library_type="group") for move_item_to_different_library.

list_item_types

Read-only

list_item_fields

Read-only

list_item_type_fields

Read-only

Check before create_item/update_item instead of guessing — what fields a given item_type accepts.

list_item_creator_types

Read-only

Same, for creators entries' creatorType.

list_creator_fields

Read-only

Name-shape fields (firstName, lastName, name, ...) valid on a creators entry itself — not the same as list_item_creator_types (roles).

list_attachments

Read-only

get_fulltext

Read-only

download_attachment

Read-only

Content returned as content_base64 — server has no access to the caller's local filesystem.

list_notes

Read-only

export_bibliography

Read-only

Formatted HTML bibliography/citation entries (in a given CSL style) or portable export data (csljson, bibtex) for a list of item keys. Unknown keys silently omitted.

create_item

Safe write

create_collection

Safe write

create_saved_search

Safe write

update_collection

Safe write

✓

update_item

Safe write

✓

update_publication_status

Safe write

✓

Preprint → published: patches fields and, uniquely, item_type in place. Accepts idempotency_key — see "Idempotency" above.

add_tags

Safe write

✓

remove_tags

Safe write

✓

set_tags

Safe write

✓

rename_tag

Safe write

Library-wide — acts on every item carrying the tag, not just one; no per-tag version. Can block on large libraries: #6.

add_to_collection

Safe write

✓

remove_from_collection

Safe write

✓

trash_item

Safe write

✓

Reversible soft delete — undo with restore_from_trash; doesn't break Word citations unless later permanently deleted or the trash is emptied.

restore_from_trash

Safe write

✓

upload_attachment

Safe write

Content sent as content_base64 — server has no access to the caller's local filesystem.

create_note

Safe write

update_note

Safe write

✓

delete_item_permanently

Destructive

✓

Breaks Word citations. Accepts idempotency_key — see "Idempotency" above.

move_item_to_different_library

Destructive

✓

Recreates the item under a brand-new key in the target library, then deletes the original — breaks Word citations. Accepts idempotency_key, strongly recommended here — see "Idempotency" above.

delete_collection

Destructive

✓

Cascades to sub-collections (matching Zotero's own "Delete Collection"); never deletes the items filed in them. Accepts idempotency_key.

delete_tag

Destructive

Library-wide — acts on every item carrying the tag, not just one; no per-tag version. Accepts idempotency_key.

delete_saved_search

Destructive

Low-risk — a saved search is just a stored filter, never touches items or citations. Accepts idempotency_key.

Testing

uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest

Tests 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 iss param (RFC 9207) sent but not advertised. The final authorization redirect built in complete_login() (app/oauth_provider.py) includes iss, which hardens the flow against mix-up attacks (RFC 9207 §2). The matching authorization_response_iss_parameter_supported flag in /.well-known/oauth-authorization-server is not set: that document is generated by the mcp SDK, which has no setting for it as of mcp 2.3.0. Without the flag, clients don't have to validate iss, 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_client in app/oauth_provider.py) is built on DCR — needed because some MCP clients (observed: Claude Desktop/claude.ai) skip registration and send /authorize an unregistered client_id directly (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_tag can block on large libraries — tracked as #6; candidate for the spec's tasks extension. mcp 2.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

MIT

Available Tools

39 tools
add_tagsA
Idempotent
Inspect

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_collectionA
Idempotent
Inspect

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.

delete_collectionA
DestructiveIdempotent
Inspect

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_permanentlyA
DestructiveIdempotent
Inspect

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_tagA
DestructiveIdempotent
Inspect

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_attachmentA
Read-only
Inspect

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_bibliographyA
Read-only
Inspect

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_fulltextA
Read-only
Inspect

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_itemA
Read-only
Inspect

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_attachmentsA
Read-only
Inspect

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_collectionsA
Read-only
Inspect

List all collections in the library (key, name, parent_collection). Read-only.

Inputs: no named parameters. Returns: result

list_creator_fieldsA
Read-only
Inspect

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_groupsA
Read-only
Inspect

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_typesA
Read-only
Inspect

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_fieldsA
Read-only
Inspect

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_fieldsA
Read-only
Inspect

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_typesA
Read-only
Inspect

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_notesA
Read-only
Inspect

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_searchesA
Read-only
Inspect

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_tagsA
Read-only
Inspect

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_trashA
Read-only
Inspect

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_libraryA
Destructive
Inspect

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_collectionA
Idempotent
Inspect

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_tagsA
Idempotent
Inspect

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_tagA
Idempotent
Inspect

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_trashA
Idempotent
Inspect

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_itemsA
Read-only
Inspect

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_tagsA
Idempotent
Inspect

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_itemA
DestructiveIdempotent
Inspect

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_collectionA
Idempotent
Inspect

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_itemA
Idempotent
Inspect

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_noteA
Idempotent
Inspect

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_statusA
Idempotent
Inspect

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

    A3.9/5.0

    Scored across 39 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to search a Zotero library, retrieve item metadata, and access full-text PDF contents through MCP tools.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to search a Zotero library, retrieve complete item metadata, and access full-text content such as PDFs through MCP tools.
      -