Zotero MCP: Your Citation Library as an Agent Tool

A reference manager becomes much more useful when the agent can ask it directly.

Zotero MCP connects your Zotero library to AI assistants through the Model Context Protocol. The agent can search the library, retrieve metadata and full text, inspect annotations, and export BibTeX. When you configure write access, it can also add or update items.

Current source version: 0.12.4

Package: zotero-mcp-server

Why it matters

A Zotero library is accumulated judgment: years of deciding what was worth keeping, which collection it belonged in, which passages deserved a highlight. Without a connection, an agent writes around that record, drawing on its training-data impression of the field instead - the path by which plausible but unverifiable citations enter drafts.

Connecting the library changes what can be checked. Citation keys come from your bibliography rather than pattern-matching; a claim can be tested against the paper you actually read; the annotations you made at reading time resurface at writing time. The library remains the source of record, and the agent finally treats it as one.

Tools

Toolsets and context cost

Version 0.9 reduced the default surface from 62 tools to 38 (about 13,448 schema tokens). The default profile exposes core tools plus libraries, search-admin, and pdf-geometry; Scite, duplicate detection, corpus discovery, feeds, and explicit related-item links are opt-in. A disabled group is absent, not merely hidden, so enable the capability your workflow needs:

{
  "ZOTERO_MCP_TOOLSETS": "scite,duplicates"
}

Use all for the full surface or none for core tools only. Unknown group names fail at startup rather than silently serving the wrong surface.

Version 0.12.1 made SQLite the default read backend in local mode when the database is readable, with API fallback for reads it cannot answer faithfully. Set ZOTERO_BACKEND=api to use the API instead. Version 0.12.4 adds batch annotations and page-image reads for equations, figures, and tables that text extraction cannot preserve; page images and layout detection need the pdf extra.

Annotation deletion in 0.12.4 is permanent, not a move to Zotero's Trash. Review an agent's proposed deletions before allowing them. The CLI now reports detected write failures with a nonzero exit status rather than wrapping those failures as successful JSON.

Host support

Zotero MCP is a standard MCP server. It works anywhere a host can launch Python tools over stdio.

The server supports local, web, and hybrid modes. Local mode is best when Zotero is installed on the same machine and you want offline reads. Web or hybrid modes make sense when writes or cloud-library access matter. Remote mode can optionally fetch attachments through WebDAV using ZOTERO_WEBDAV_URL, ZOTERO_WEBDAV_USERNAME, and ZOTERO_WEBDAV_PASSWORD.

Install

Three practical routes:

• Via Carrel — run /carrel-setup and say yes when the interview asks about Zotero or citation-library integration. Carrel adds the MCP at project level and prompts for the relevant setup.
• Via the agent skill — after installation, run zotero-mcp install-skill in a project. It detects configured harnesses and installs the small zotero-cli skill without copying the full MCP schema into every request.
• Manually — install the server and register it with your MCP host.

You need Python 3.10 or newer, and Zotero 7 or newer if you want local full-text access.

Default install:

uv tool install zotero-mcp-server
zotero-mcp setup

zotero-mcp setup writes the host configuration for you. pip and pipx install the same package.

With heavier extras:

uv tool install "zotero-mcp-server[semantic]"   # embeddings + vector index
uv tool install "zotero-mcp-server[pdf]"        # PDF outlines, layout, page images, EPUB annotations
uv tool install "zotero-mcp-server[scite]"      # citation tallies, retraction alerts
uv tool install "zotero-mcp-server[all]"        # all of the above

The base install is the right default for most researchers. Add extras only when you need semantic search, PDF outline extraction, EPUB annotation support, or citation-intelligence features.

For container deployments, upstream publishes core and all image flavours with stdio and streamable-HTTP modes. Follow the Docker image documentation for tags, environment variables, and persistence paths.

Let Zotero answer

For local API access, turn on Allow other applications on this computer to communicate with Zotero in Zotero's settings under Advanced. Keep Zotero running for API fallback and local writes. SQLite-backed reads can also work while Zotero is closed, provided its database is accessible.

Register it with the host

For Claude Desktop, zotero-mcp setup does this for you. For Claude Code, the server goes in ~/.claude.json:

{
  "mcpServers": {
    "zotero": {
      "command": "zotero-mcp",
      "env": {
        "ZOTERO_LOCAL": "true"
      }
    }
  }
}

ZOTERO_LOCAL: "true" on its own is enough for reading, and reading is most of the work. On Zotero 10 or newer, optional local writes can stay on the same machine: run zotero-mcp authorize-local and choose Always Allow in Zotero's dialog if you want reusable authorization. A local authorization key is distinct from a zotero.org API key. Use zotero-mcp authorize-local --status to inspect the available write path without printing the key.

For older Zotero versions, or when you prefer web writes, add ZOTERO_API_KEY and ZOTERO_LIBRARY_ID (your numeric user ID, printed on the same Zotero security settings page that issues the key). The server then runs hybrid, reading locally and writing over the web. Set ZOTERO_LOCAL_WRITE=false to keep writes on the web API even when a local key exists.

Two traps are worth naming. Environment variables set in the shell you launch the host from will override whatever the config file says. And GUI applications do not reliably inherit your shell PATH, so if a host reports that it cannot find zotero-mcp, give it the absolute path that zotero-mcp setup-info prints.

The CLI, for agents with a shell

The same package installs zotero-cli, a standalone terminal interface to the library that needs no AI assistant at all. This matters more than it first sounds. An agent that already has a shell, such as Claude Code or Codex, can call the CLI directly, and a shell command costs far fewer tokens than the equivalent MCP tool schemas, which occupy context whether or not the agent ends up using them.

zotero-cli search "attention mechanisms" --mode semantic
zotero-cli get metadata ABC123 --format bibtex
zotero-cli add doi 10.1038/s41586-021-03819-2 --collections "Reading List"
zotero-cli ann search "boundary condition"

Adds are idempotent by default: run the same add twice and the second run files the existing item into any collections it was missing rather than creating a duplicate. Both surfaces read the configuration that zotero-mcp setup already wrote, so there is nothing further to arrange.

Full documentation, including the ChatGPT setup path, lives at the Zotero MCP docs.

Part of Research Memex

Zotero MCP is the citation-library counterpart to the document and memory tools:

• Carrel sets it up when the interview surfaces Zotero.
• MinerU turns difficult PDFs into AI-ready text; Zotero MCP keeps the reference graph and annotations reachable.
• Memex Plugin remembers why papers mattered in a session; Zotero remains the bibliographic source of record.
• Research Scanner can feed new candidates into Zotero for durable tracking.

Use Zotero MCP when the answer depends on what is actually in your library. You can check citation coverage, what you already read, which annotations support a claim, or whether a draft cites the right sources.