Zotero MCP: connecting a Zotero library to Claude, ChatGPT and Cursor

The gap Zotero MCP fills between a reference manager and an assistant

Zotero stores your papers, annotations and collections, but it has no way to hand that material to a chat assistant. Copying metadata by hand is the usual workaround, and it does not scale past a handful of items. Zotero MCP puts a Model Context Protocol server in front of the library so an assistant can search items, read metadata, pull annotations and, in the newer releases, write back.

The audience is narrow but real: researchers who already live in Zotero and who also work inside Claude Desktop, ChatGPT, Cursor, Cherry Studio, Chorus or similar clients. The README lists those clients by name. The project also ships a standalone CLI, zotero-cli, for people who want the same access from a terminal without an assistant in the loop, which is the part that makes it useful for scripting and automation rather than only for chat.

Local mode, web API mode, and the hybrid in between

The access model has three shapes. Local mode talks to a running Zotero instance and needs no API key, so it works offline. Web API mode uses ZOTERO_API_KEY and ZOTERO_LIBRARY_ID against the cloud library. Hybrid mode reads from local Zotero and writes through the web API, which the README describes as the option for local-mode users who still need writes.

That third mode exists because local writes are gated. The .env.example notes that local write requires Zotero 10 or newer, and that ZOTERO_LOCAL_WRITE defaults to auto, with false forcing writes back through the Web API. Credentials for local write are normally written by zotero-mcp authorize-local into the config file; ZOTERO_LOCAL_API_KEY and ZOTERO_LOCAL_SERVER_ID exist for containers and CI where a config file is awkward.

The dependency floor in pyproject.toml is worth reading before you upgrade anything. pyzotero is pinned to >=1.14.0 for local API write support, and the comment states that 1.13.5 is required because it retries rate-limited reads and raises TooManyRetriesError once backoff is exhausted. Below that version, the comment says every read method returns the HTTP 429 body as bytes, which callers read as data, and that dedup searches suffer most because a throttle looks like "no match" and can duplicate an item. That is an unusually explicit statement of why a minimum version is load-bearing rather than preferred.

Installing Zotero MCP and running a first search

The base install is deliberately small. The README states it includes search, metadata retrieval, annotations and write operations, and pulls in no ML or AI dependencies. The recommended route is uv:

uv tool install zotero-mcp-server
zotero-mcp setup  # Auto-configure (Claude Desktop supported)

pip and pipx are also documented as equivalent paths. The setup command is what writes the client configuration; the README notes Claude Desktop is the supported target for auto-configuration, so other clients may need manual wiring.

Heavy parts are split into extras. Semantic search needs the semantic extra, PDF outline extraction and EPUB annotations need pdf, and Scite citation tallies need scite. Installing everything is explicit:

uv tool install "zotero-mcp-server[all]"
uv tool install "zotero-mcp-server[semantic]"

With the server configured, a first useful query is a library search from the assistant. The CLI gives the same access without one. The README describes --json on every command for pipelines and agents, and short aliases (s, g, ann, coll) for interactive use, so a terminal check looks like a search command with the JSON flag rather than a bespoke output format. If you want to confirm the install and its version before touching a real library:

zotero-mcp update --check-only

That command checks for updates without applying them, which is the cheapest way to confirm the tool is on PATH and reachable.

The agent skill route and its context-cost argument

The most interesting design decision in the repository is not the MCP server at all. It is the agent skill, installed with a single command:

zotero-mcp install-skill

The README states it detects the harnesses in your project and installs to each, with no flags and no per-tool instructions. The argument is about fixed context cost. An MCP server sends every tool's schema on every request, before the user types anything. The README's table puts the default profile at 38 tools and 13,448 tokens in context on every request, against 98 tokens for the skill's frontmatter until the agent decides it is relevant, and 1,368 once the body loads. It reports roughly 137x cheaper before either is used and about 10x once the skill has fired, and points to python scripts/measure_context_cost.py to re-measure.

The README is careful about what this does not prove: it says the figure is fixed context cost only, that it does not measure task success or round trips, and that a cheaper surface which gets the answer wrong is not cheaper. That caveat is doing real work, and it is the honest way to present the number. The practical split the README draws is: use the MCP server when the client speaks MCP but has no shell (Claude Desktop, ChatGPT), and use the skill when the client has a shell (Claude Code, Cursor, Codex, Windsurf, Gemini CLI, Amp, OpenCode).

Where Zotero MCP is the wrong tool

The clearest boundary is the client. If your assistant has no MCP support and no shell, neither route applies. Claude Desktop and ChatGPT are named as the MCP-side targets, and the skill route requires shell access, so a browser-only or mobile-only workflow is out of scope.

The second boundary is installation weight. The base package is light, but semantic search pulls ChromaDB and sentence-transformers, and the Dockerfile is blunt about the consequence: sentence-transformers brings torch, and torch's default PyPI wheel depends on the CUDA stack, including nvidia-cudnn at roughly 445 MB, nvidia-cusparselt at roughly 221 MB and triton at roughly 185 MB. The Dockerfile states none of it is usable in python:3.10-slim, which ships no CUDA runtime and is not run with --gpus, and that downloading around 850 MB of wheels through QEMU-emulated linux/arm64 truncates and fails pip's hash check. The Dockerfile works around this by installing the CPU-only torch build from PyTorch's index first. If you are not prepared to accept that download, install without the semantic extra.

The third boundary is write safety. The pyzotero comment about throttled reads being mistaken for empty results and duplicating items is a warning about a failure mode that is easy to miss, because the visible symptom is a plausible answer rather than an error. Anyone running dedup or merge operations against a large library should treat that as the area to verify first. The README documents a dry-run preview for finding and merging duplicates, which is the right default, but the README does not document rollback.

How it compares with the Scite Zotero plugin

The nearest named alternative in the repository is the Scite Zotero plugin, which the README references directly when describing the optional scite extra. The difference is architectural rather than a matter of feature lists. The Scite plugin is a Zotero extension: it lives inside the Zotero client and surfaces citation tallies and retraction information in the Zotero interface itself. Zotero MCP does not extend Zotero. It sits outside as a server and a CLI, and exposes the library to external programs. The scite extra is an attempt to bring comparable citation intelligence into that external surface, using public API endpoints, and the README states no Scite account is required.

So the choice follows from where you work. If you want citation context while reading inside Zotero, the plugin is the shorter path. If you want an assistant or a script to query the library, the plugin cannot help, because it has no protocol surface for an external client to call.

Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-08-25, which is recent enough that the project is not in a dormant state. Release cadence in the recent record is tight: v0.9.1 on 2026-08-06, v0.10.0 on 2026-08-24 and v0.11.0 on 2026-08-25. Frequent minor releases on a 0.x version line mean the upgrade path matters more than it would for a stable-versioned library.

The project provides an upgrade command rather than leaving it to the package manager:

zotero-mcp update --check-only
zotero-mcp update

The README states that zotero-mcp update preserves all configurations, which is the claim to verify on your own setup rather than assume, since configuration for this tool spans a client config file, a .env file and possibly semantic-search state.

Licensing is MIT, declared both in the repository metadata and in pyproject.toml as license = {text = "MIT"} with the matching classifier. MIT is permissive and imposes no copyleft obligation on your own code. The dependency tree is a separate question: the semantic extra brings in ChromaDB, sentence-transformers and embedding providers, and the scite extra calls public Scite endpoints. Those carry their own terms, and the README does not summarise them. This is a description of what the files say, not legal advice.

Editorial conclusion

Adopt Zotero MCP if your assistant speaks MCP but has no shell, or if you want a scriptable zotero-cli over the same config. Skip it if you cannot run a local Zotero instance or a Python 3.10+ environment, and skip the semantic extra if you will not accept a torch download. Before trusting it with a real library, run zotero-mcp update --check-only, confirm which mode you are in with zotero-mcp setup, and test one write path, such as adding a paper by DOI, against a throwaway collection rather than your working one.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes