Zotero MCP: Complete Guide (2026)

TL;DR + what you actually need

• One package: zotero-mcp (the kujenga implementation, Python, MIT). It runs via uvx and is a local stdio server — your MCP client launches it as a subprocess. There is no hosted/remote endpoint.
• One decision: local API or Web API. Set ZOTERO_LOCAL=true to read the Zotero desktop app running on your machine (fast, private, no key). Or leave it off and supply ZOTERO_API_KEY + ZOTERO_LIBRARY_ID to reach your library through Zotero’s cloud.
• Three tools, read-only: zotero_search_items, zotero_item_metadata, zotero_item_fulltext. This server reads your library; it does not add, edit, or cite. (If you need writes, jump to the landscape section.)

The copy-paste config, if that’s all you came for — local mode, works with the Zotero desktop app open:

{
  "mcpServers": {
    "zotero": {
      "command": "uvx",
      "args": ["--upgrade", "zotero-mcp"],
      "env": {
        "ZOTERO_LOCAL": "true",
        "ZOTERO_API_KEY": "",
        "ZOTERO_LIBRARY_ID": ""
      }
    }
  }
}

Before that config does anything, you have to turn on Zotero’s local API — a single checkbox covered in Local API vs Web API. The rest of this guide explains the decisions behind the config and where the sharp edges are.

What Zotero MCP actually does

Zotero is the open-source reference manager researchers use to collect papers, store PDFs, and generate citations. The Zotero MCP server is a stdio process — a local subprocess your MCP client launches — that turns tool calls from the model into authenticated requests against your Zotero library. Ask “what methods have my saved papers used to measure attention?” and the agent calls zotero_search_items, gets real hits from your library, then chains zotero_item_fulltext to read the PDFs it found and answers from your sources instead of its training data.

The named pieces are worth getting straight once, so the rest lands:

• MCP client — the AI app (Claude Desktop, Cursor, VS Code, Claude Code) that speaks the protocol and shows the tools to the model.
• The server — zotero-mcp, launched by the client, that exposes three tools over stdio.
• The backend — either the Zotero desktop app’s local API or the hosted Web API. This is the one choice you make at setup.
• Item — a single library entry (a paper, book, or note), identified by an item key. Tools take a key and return metadata or text.

The design philosophy is stated plainly in the README: implement “a small but maximally useful set of interactions.” Three tools is not an oversight — it is the pitch. You get search, metadata, and full text, and nothing else to reason about. Whether that minimalism is the right call depends entirely on your workflow, which is the next section.

Which Zotero MCP? (there are three)

“Zotero MCP” is not one project. A well-upvoted r/zotero thread asking “anyone using Zotero with MCP?” laid out the same three implementations most people land on, and the distinctions are sharper than roundups admit — they even ship under different PyPI names, which is a genuine install trap.

The trap in that first column: uvx zotero-mcp installs kujenga’s three-tool reader, while the feature-rich 54yyyu fork ships on PyPI as zotero-mcp-server. People install one expecting the other’s features and file a “where’s the semantic search?” issue. MCP.Directory’s /servers/zotero catalog entry — and this guide’s install card — track the kujenga server. That is a deliberate choice: it is the smallest thing that works, has no ML dependencies to install, and is the right starting point for “can I chat with my library at all?”

Our recommendation: start with kujenga. Confirm the connection works and that reading your papers in Claude is genuinely useful before you take on the heavier fork. Move to 54yyyu/zotero-mcp the moment you need one of its headline features: vector search over the whole library, PDF annotation extraction, or the ability to add papers by DOI. They are not competitors so much as two rungs of the same ladder.

Where does the community’s enthusiasm actually point? Tom Dörr’s widely shared post is a fair proxy — note that it drew more bookmarks than likes, the classic “save it to set up later” signal from a research-leaning audience:

The tell: that post links to the maximal 54yyyu fork, not the minimal reader. People chase the fully-featured version — and then, per the threads below, bounce off the setup. Starting minimal is how you avoid that.

Local API vs Web API (the one real decision)

Everything else is copy-paste; this is the choice that determines whether your setup works. The kujenga server can reach your library two ways, and they have different trade-offs.

Turning on the local API

The README calls the local API “a bit more responsive,” and it needs no key, so it is the right default for a library that lives on your laptop. Enable it once:

1. Open Zotero and go to Settings → Advanced.
2. Check “Allow other applications on this computer to communicate with Zotero.”
3. Leave Zotero running — the local API is served by the desktop app, so if the app is closed the tools return connection errors.

One gotcha the issue tracker documents repeatedly: zotero_item_fulltext hits a /fulltext endpoint that only arrived in Zotero 7.1. On older builds it 404s while search and metadata work fine. If full text is the whole point for you, either update Zotero or use the Web API instead.

Using the Web API

Pick the Web API when the library is not on the machine running the agent — a server, a different laptop, or a shared group library. Create a key and find your library ID (usually your numeric user ID) at zotero.org/settings/keys, then set ZOTERO_API_KEY and ZOTERO_LIBRARY_ID and drop ZOTERO_LOCAL (or set it to false). Set ZOTERO_LIBRARY_TYPE=group if you’re pointing at a group library rather than your personal one. The kujenga repo also publishes a Docker image (ghcr.io/kujenga/zotero-mcp) aimed squarely at this Web-API path.

Install (every client)

The server is stdio-only: every client launches uvx --upgrade zotero-mcp as a subprocess with the env vars above. The install panel below pulls its config from the canonical /servers/zotero catalog entry, so the package name and env shape stay in sync. Pick your client, copy, fill in your mode (local or Web), restart.

One-line install · Zotero

Open server page

Install

Cursor

One-click install

1-Click

VS Code

One-click install

1-Click

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

Client-specific notes:

• Prerequisite: uvx ships with uv, Astral’s Python package runner. Install uv first (curl -LsSf https://astral.sh/uv/install.sh | sh on macOS/Linux) or the server won’t launch. Prefer not to use uv? The README’s fallback is pipx run zotero-mcp.
• Claude Desktop — paste the JSON block from the install card into claude_desktop_config.json (on macOS: ~/Library/Application Support/Claude/), then restart the app. The tools appear under the server name zotero.
• Cursor — same JSON shape in ~/.cursor/mcp.json. See /clients/cursor.
• VS Code — drop the snippet into the workspace or user MCP config; the tools show up in the agent’s tool list after a reload.

Codex CLI

Codex reads MCP servers from ~/.codex/config.toml. Mushtaq Bilal’s widely shared “connect Zotero with Codex” walkthrough uses exactly this shape:

[mcp_servers.zotero]
command = "uvx"
args = ["--upgrade", "zotero-mcp"]

[mcp_servers.zotero.env]
ZOTERO_LOCAL = "true"
ZOTERO_API_KEY = ""
ZOTERO_LIBRARY_ID = ""

Restart Codex and confirm with codex mcp list. Browse every supported client and its config path at mcp.directory/clients.

The three tools

Small surface, so here is the whole thing. Each tool returns formatted text the model reads directly, and Claude chains them naturally — search first, then metadata or full text on the hits.

• zotero_search_items — search your library with a text query and get back matching items (title, authors, keys). This is the entry point for almost every workflow. It returns a bounded set of results, not your entire library, so specific queries beat broad ones.
• zotero_item_metadata — given an item key, return detailed metadata: authors, year, publication, abstract, tags, and the fields Zotero stores. Cheap in tokens and the right call when you want bibliographic detail without the full PDF.
• zotero_item_fulltext — given an item key, return the full text (the PDF contents Zotero has indexed). This is the expensive one, both in tokens and in setup: on the local API it needs Zotero 7.1+, and it only works for items with indexed text.

What is deliberately absent is as important as what is present. There is no “add item,” no “insert citation,” no annotation tool, no collection browsing. If your mental model of “AI + Zotero” includes the assistant writing to your library, this server will disappoint you — and that is by design, not a bug. Our take: the three-tool surface is the right primitive for retrieval-augmented answering, and the wrong tool for citation management.

Recipes

Four workflows where the five-minute setup pays off. All assume the server is connected and (for full text) Zotero 7.1+ in local mode.

Recipe 1 — Literature synthesis from your own library

“Search my library for papers on spaced repetition, read the three most relevant, and give me a synthesis of their methods and where they disagree.” The agent runs zotero_search_items, picks hits, pulls zotero_item_fulltext on each, and reasons across them. This is the flagship use case the r/zotero thread was chasing: RAG over your papers, grounded in sources you already vetted. For a structured version of this, pair it with our literature-review skill.

Recipe 2 — Draft-time citation lookup

“I claimed X in this paragraph — which of my saved papers actually supports it? Give me the authors and year.” Search plus zotero_item_metadata turns a vague memory (“I read something about this”) into a concrete citation candidate while you write. It pairs naturally with the scientific-writing skill for the drafting half.

Recipe 3 — “Have I already saved this?”

“Do I have anything in my library by this author on transformer interpretability?” A quick zotero_search_items answers the question every researcher asks before downloading a paper twice. Fast, and exactly what the local API is good at.

Recipe 4 — Explain a dense paper you saved months ago

“Pull the full text of the Vaswani attention paper from my library and walk me through the positional-encoding section like I’ve forgotten it.” zotero_item_fulltext feeds the PDF text to the model, which explains it in context. This is where keeping full text local (no re-uploading PDFs to a chat UI) is a real convenience.

Limits + what we got wrong

Honest constraints, including the assumptions that burned us while testing.

• Read-only. The kujenga server cannot add references, edit items, or insert citations. “Can I use this to insert new references?” is an open question on the issue tracker; the answer is no. Writes live in the 54yyyu fork.
• What we got wrong #1: we assumed zotero_item_fulltext would just work. On a stable Zotero install it 404’d — the local /fulltext endpoint only shipped in 7.1. Updating Zotero fixed it instantly.
• What we got wrong #2: we assumed uvx was on PATH. On a fresh machine it wasn’t, and the client failed with spawn uvx ENOENT and no tools. Installing uv first is the fix — the config is downstream of that.
• Local mode needs the app open. The local API is served by the Zotero desktop application. Close Zotero and every tool call fails. On a headless server, you must use the Web API.
• Large libraries strain the heavy features. One r/zotero user found the feature-rich fork “stayed stable past 10,000 items” only because it read the local database directly, and called kujenga’s server “lighter.” Either way, search returns a bounded page, and dumping the full text of many papers into one context is the fast way to blow your window — retrieve narrowly.
• No hosted option. There is no remote URL to point a client at; it is a local subprocess (or your own Docker container). That is fine for a personal setup and awkward for a team.

Troubleshooting

Community signal

The most useful artifact for a first-timer isn’t the tweet above — it’s the r/zotero thread that mapped all three implementations and then argued about them in the comments. That is where the honest signal lives. The 54yyyu maintainer showed up to thank users for adopting a tool they “originally built for myself.” One researcher reported a server “stayed stable when the library passed 10k items” by reading the local database directly, while noting annotation extraction left “messy highlight artifacts.” A blunter, contrarian voice: “been trying all of the above but none seems to work with Zotero so far… and I am not sure how safe and secure it is.”

Both reactions are correct. The tooling is genuinely useful and genuinely fiddly to set up, and the privacy question is real — which is exactly why the local API (nothing leaves your machine) is the default we recommend. On the academic side, Mushtaq Bilal’s popular “academics should use Claude Code and Codex” thread and its Zotero walkthrough show the same demand from working researchers, not just tinkerers.

The verdict

FAQ

Sources

• Primary implementation (catalog default): github.com/kujenga/zotero-mcp (README: tools, local vs Web API, config options) and its issue tracker (fulltext 404 / Zotero 7.1, spawn uvx ENOENT, the “insert references” feature request cited above)
• PyPI package (installed by the card): pypi.org/project/zotero-mcp
• Feature-rich fork: github.com/54yyyu/zotero-mcp (PyPI: zotero-mcp-server) and the TypeScript, cloud-focused kaliaboi/mcp-zotero
• Zotero Web API + key management: zotero.org/settings/keys and the Web API v3 docs
• Community: r/zotero — “Anyone using Zotero with MCP?” (three-implementation comparison, big-library and security reactions) and Tom Dörr’s post
• Canonical MCP.Directory entry: /servers/zotero
• Related reading: Best knowledge-base MCP servers (2026)