Zotero MCP: Connect Zotero to AI Assistants

Zotero MCP is a community-built server that lets an AI assistant search, read, annotate and add items in your Zotero library through the Model Context Protocol (MCP). It is not an official Zotero product: the project is maintained by its author on GitHub (54yyyu/zotero-mcp) under an MIT licence, and Zotero itself does not ship an MCP server. This guide is for researchers who already keep references in Zotero and want to ask Claude or another assistant questions about their own library. After reading it you should be able to install the server, connect it to a client, run a first query, and diagnose the common failures. Details were checked against the project’s README, tool reference and troubleshooting page on 2026-11-07.

What it is used for in research

MCP is described by its maintainers as an open-source standard for connecting AI applications to external systems. A Zotero MCP server is the adapter on the Zotero side: the AI client calls its tools, and the tools read from (and, if you allow it, write to) your library. According to the project’s tool reference, the tools fall into these groups:

Search: keyword search, advanced multi-criteria search, listing collections, tags and recent items, searching by tag (zotero_search_items, zotero_advanced_search, zotero_get_collections, zotero_get_tags, zotero_get_recent).
Semantic search: similarity search using embeddings (zotero_semantic_search); needs the optional [semantic] extra.
Reading: item metadata (including BibTeX), full text, child attachments and notes, and page ranges of a PDF as Markdown (zotero_get_item_metadata, zotero_get_item_fulltext, zotero_read_pdf_pages).
Annotation and notes: read annotations, create highlights or area annotations, build a per-paper annotation digest, create or edit notes.
Adding items: by DOI, URL, ISBN, BibTeX, CSL JSON or a local PDF/EPUB file, with open-access PDF attachment for DOIs.
Optional groups: Scite citation tallies and retraction checks, duplicate merging, related-paper discovery through OpenAlex, RSS feeds.

Typical requests, taken from the project’s own examples, are “Find papers in my library on attention mechanisms” or “Summarize the key findings of this paper”. For how Zotero itself is organised (libraries, collections, groups), see Zotero for researchers.

What leaves your machine

Editorial note, not a statement from the project: whatever the assistant reads from your library (metadata, notes, PDF text) is passed into the AI client’s conversation, so it is handled under that client’s data terms. Check your institution’s rules before connecting a library that holds unpublished manuscripts, participant-derived data or confidential peer-review material. The project also states that its Scite tools call scite.ai’s public endpoints, and that embedding-based semantic search can use OpenAI, Gemini or Ollama, or a local model.

Install or access (official source only)

Use the project’s own repository and its PyPI package, zotero-mcp-server (github.com/54yyyu/zotero-mcp). It requires Python 3.10 or later.

uv tool install zotero-mcp-server
# or
pip install zotero-mcp-server

Optional extras, each installed the same way (for example pip install "zotero-mcp-server[semantic]"):

Extra	What it adds
`semantic`	Semantic search (ChromaDB, sentence-transformers, OpenAI or Gemini embeddings)
`pdf`	PDF outlines, page layout and page images, EPUB annotations
`scite`	Scite citation tallies and retraction alerts; no Scite account needed per the README
`all`	All of the above

Update at any time with zotero-mcp update.

Step-by-step: connect Zotero to Claude

Install the package with one of the commands above.
Turn on Zotero’s local API. In Zotero 7 or later, open Settings > Advanced and tick Allow other applications on this computer to communicate with Zotero. Keep Zotero running while you use the assistant.
Connect your assistant.
- Claude Desktop: run zotero-mcp setup, which configures it automatically. To do it by hand, add this to claude_desktop_config.json:
```
{
  "mcpServers": {
    "zotero": {
      "command": "zotero-mcp",
      "env": { "ZOTERO_LOCAL": "true" }
    }
  }
}
```
- Claude Code: add the same mcpServers entry to ~/.claude.json. Clients with a shell can alternatively run zotero-mcp install-skill (see the comparison below).
- ChatGPT, Cherry Studio, Chorus and other clients: follow the project’s Getting started page.
Optional, for writing to your library. On Zotero 10 or later, run zotero-mcp authorize-local once and choose Always Allow. On older versions, set ZOTERO_API_KEY and ZOTERO_LIBRARY_ID so writes go through the Zotero web API.
Restart the client and ask a question, such as “Find papers in my library on attention mechanisms”.

Version matrix

Zotero version	Reading	Writing
7 or later	Local API (enable in Settings > Advanced); full-text access needs 7+	Not via the local API unless Zotero 10+
10 or later	Local API	Local writes after `zotero-mcp authorize-local`
9 and older	Local API is read-only	Set an API key and library ID alongside `ZOTERO_LOCAL=true` (hybrid mode)

Source: the project’s README and troubleshooting page. Use zotero_write_capabilities inside the assistant to see which write path your setup has (local, hybrid, web or none).

Output and how to read it

The assistant returns results as ordinary chat answers built from tool calls, so the quality of what you see depends on both the server and the model. Practical points that follow from the tool reference:

Metadata calls can return Markdown, raw JSON or BibTeX (format="markdown"|"json"|"bibtex"), so you can ask for BibTeX directly and compare it with the item in Zotero.
PDF reading returns Markdown for a page range, and flags pages whose math, figures or tables the text extraction garbles; format="image" returns the page as an image instead. Treat any numeric result or equation the assistant quotes as unverified until you open the PDF page.
Annotations created by the assistant can be edited with zotero_update_annotation; zotero_delete_annotation removes one permanently.
Semantic search ranks by meaning, not by exact phrase, so results are leads to check rather than a complete search. For a systematic review, use database searches with documented strategies instead.
Context cost. The README states that every tool schema is sent on every request: about 16,815 tokens for the default 41-tool profile and 20,942 for all 53 tools. Set ZOTERO_MCP_TOOLSETS (for example none for core tools only, or scite,duplicates to add groups) to trim that.

When the assistant cites a Scite tally or a retraction alert, that information comes from scite.ai; see Scite AI for how its labels work and where they fall short.

Troubleshooting

Symptom	What the project’s troubleshooting page says
Searches return no results	Zotero must be running and its local API enabled (Settings > Advanced).
Claude Desktop cannot find `zotero-mcp`	Use the absolute path to the executable; `zotero-mcp setup-info` or `which zotero-mcp` shows it.
Full text unavailable	Full-text access needs Zotero 7 or later. Environment variables override the client’s config.
Writes fail on Zotero 9 or older	The local API is read-only; set `ZOTERO_API_KEY` and `ZOTERO_LIBRARY_ID` with `ZOTERO_LOCAL=true`.
Semantic search is stale or empty	`zotero-mcp update-db` builds the index; `db-status` checks it; `update-db --fulltext` includes full text. `update-db --force-rebuild` deletes and re-embeds everything, which is charged again with OpenAI or Gemini embeddings. The index lives in `~/.config/zotero-mcp/chroma_db/`; try `repair-db --dry-run`, then `repair-db`.
HTTP transport returns 421 or 403	Set `FASTMCP_HTTP_ALLOWED_HOSTS` and `FASTMCP_HTTP_ALLOWED_ORIGINS`.
“Error loading hnsw index” on Windows	Occurs with a non-ASCII user folder name; move `persist_directory` to an ASCII-only path.

Alternatives

The same project ships three routes; the README presents them as one package, zotero-mcp-server.

Route	Intended for (per README)	How to start
MCP server	Chat apps that speak MCP but have no shell: Claude Desktop, ChatGPT, Cherry Studio, Chorus	`zotero-mcp setup`
`zotero-cli` plus agent skill	Agents with a shell: Claude Code, Codex, Cursor, Windsurf, Gemini CLI, Amp, OpenCode. Stated context cost is 98 tokens until needed, against about 17k for the MCP server	`zotero-mcp install-skill`
Zotero Agent	A chat panel inside Zotero that knows the item and page you have open	`zotero-cli plugin`, then install the `.xpi` via Tools > Plugins, the gear, Install Plugin From File

For other Zotero add-ons, see best Zotero AI plugins; to compare Zotero with other reference managers, see Zotero vs Mendeley, How to use EndNote and citation management for a research group. To query single PDFs rather than a library, see chat with PDF tools.

FAQ

Does Zotero have an official MCP server?

No. Zotero MCP is a community project by 54yyyu, distributed as zotero-mcp-server and licensed under MIT. It is not made or endorsed by the Zotero team, as far as the project’s own documentation shows.

Which Zotero version do I need?

Zotero 7 or later to enable the local API and use full-text access. Writing through the local API needs Zotero 10 or later; on Zotero 9 and older the local API is read-only and writes need a web API key and library ID.

Does it work with ChatGPT or only Claude?

The README lists Claude, ChatGPT, Cherry Studio, Chorus, Cursor and other clients. The tool reference says the ChatGPT connector tools (search and fetch) turn on automatically when the server runs over streamable-http or sse, and stay off for stdio.

Can the assistant change or delete my library?

Only if write access is set up. Local writes need the one-time zotero-mcp authorize-local step on Zotero 10+, and delete tools such as zotero_delete_annotation are permanent. Choosing Always Allow is the project’s recommended setting, so consider whether that suits a shared or irreplaceable library.

Is semantic search accurate enough for a literature review?

It finds items by similarity to a query and is useful for exploring your own library. It does not replace a documented, reproducible search strategy; use documented database searches for that.