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.15.2 (opens in a new tab)

Package: zotero-mcp-server (opens in a new tab)

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

The default profile includes core tools plus semantic, libraries, search-admin, and pdf-geometry. Without the semantic dependencies, the server removes semantic and search-admin from the available surface. Tool count and schema cost therefore depend on the installed extras and selected groups. 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 all groups supported by your installation or none for core tools only. none,semantic adds semantic search back to that minimal profile when its dependencies are installed. 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.

Earlier 0.13.x changes

Version 0.12.5 fixed SQLite field-name assumptions, collection-scoped API search, note pagination, related-paper citation failures, BibTeX export, and several local-write and semantic-index edge cases. Version 0.13.0 supports FastMCP 4 and the MCP 2026-07-28 server/discover handshake used by the ChatGPT Secure MCP Tunnel while retaining legacy initialize clients. Version 0.13.1 adds sticky-note annotations and corrects area-box placement on rotated PDF pages. The current source still exposes the local SQLite read path, optional API fallback, the zotero-cli agent skill, and the permanent-annotation-deletion warning described above.

Version 0.13.2 fixes several library maintenance risks. Duplicate merges keep distinct linked-file attachments. Incremental tag edits and merges preserve automatic-tag types; item-type changes carry fields to their compatible counterparts. Semantic re-indexing keeps old passages when replacement embedding fails and holds the sync marker while failures remain.

The release also refreshes local reads after its own writes, accepts the personal library ID returned by library listing, normalizes encoded DOI URLs, and fixes bibliography numbering. Scanner PDFs with an existing OCR text layer gain a plain-text fallback when Markdown extraction fails or returns no text. This fallback does not apply to explicit page subsets and attributes its text to the first page. Do not treat that attribution as precise page evidence.

Changes in 0.14.x

Version 0.14 adds passage finding with zotero-cli read --find. You can open PDF pages or annotations in Zotero, and create or append formatted notes. Bibliography exports now include all pages of results from collections and libraries. Failed note updates and full-text reads report errors. SQLite search handles case and accents more consistently.

Version 0.14.1 fixes concurrent semantic-index updates on Windows and supports a configurable ChromaDB index directory. It also improves HTML snapshot extraction, annotation reading order, and errors for collections outside the selected library. See the upstream changelog (opens in a new tab) before updating an existing index.

Changes in 0.15.x

The 0.15 series expands open-access PDF discovery, including OpenAlex. Review the agent's proposed source and attachment before allowing writes or downloads. Markdown and YAML attachments can contribute full text. JSON full-text reads report truncation and page coverage; semantic indexing separately reports chunking problems. A returned excerpt is not evidence that the entire document was read. Advanced searches validate their conditions, and semantic-search prompts fall back when that capability is unavailable.

Version 0.15 moves startup semantic-index updates into a child process. Version 0.15.1 adds PMID imports and fixes YAML upload handling, passage sizing for embedding models, and PDF fitting and text selection in the Agent panel. Consult the release notes (opens in a new tab) before upgrading the package or the separate Zotero Agent panel.

Version 0.15.2 adds damaged-index diagnosis and preview-first repair, idle unloading of semantic-index resources, and optional hosted reranking. Hosted reranking sends candidate passages to the configured endpoint; review that endpoint's data terms before enabling it. Read the upstream recovery instructions before applying a repair to an existing index. The package update and the separate Agent panel update remain distinct.

Zotero Agent panel

The optional Zotero Agent plugin brings Claude Code, Codex, or pi into a panel inside Zotero. It passes the open item, page, and selection to your chosen agent. The agent can use zotero-cli for library work. This is a separate interface from connecting an MCP client.

Install the Python package first. Run zotero-cli plugin --reveal to locate the plugin file. In Zotero, select Tools, then Plugins. Open the gear menu, select Install Plugin From File, and choose zotero-agent.xpi. The panel also needs Node.js and an installed, signed-in agent. Follow the Zotero Agent setup guide (opens in a new tab) for configuration and permissions.

The agent may send your messages, attached context, and material it reads to its provider. Check the agent's permissions and data terms before using sensitive library material.

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 (opens in a new tab) 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 (opens in a new tab) 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 --output-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 (opens in a new tab).

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.