zotero-claude-mcp

An MCP server that gives Claude access to your Zotero library — both the local database on your own machine and your zotero.org account, including group libraries.

Python standard library only. No pip install, no virtualenv, no dependencies to keep patched. If you have Python 3.9+, it runs.

What it does

Ask Claude things like "what do I have saved on contact-angle hysteresis?", "which of my PDFs mention level-set methods?", "summarise the abstracts in my Reading collection", or "cite these three in IEEE style" — and it reads your actual library instead of guessing or searching the web.

It can also open the PDFs: zotero_attachments returns real file paths, which Claude can then read directly.

Related MCP server: Zotero MCP

Install

git clone https://github.com/ARHashemi/zotero-claude-mcp.git
cd zotero-claude-mcp
./install.sh

That is the whole install. install.sh checks your Python, finds your Zotero library, registers the server with Claude Code at user scope (so it works in every project and session), and tells you what it found. It is safe to re-run.

Then restart Claude Code.

Nothing to configure for local use — no account, no API key, no paths. Your Zotero data directory is read from Zotero's own preferences, and your numeric user ID from the local database.

If your library lives somewhere unusual and is not found automatically, install.sh says so and offers to take the path. You can also set it any time:

bin/zotero-mcp setup --data-dir=/path/to/your/Zotero

Zotero shows that path under Settings -> Advanced -> Files and Folders.

Other MCP clients

Point any stdio-capable client at bin/zotero-mcp:

"mcpServers": {
  "zotero": {
    "command": "/absolute/path/to/zotero-claude-mcp/bin/zotero-mcp"
  }
}

Where things are looked for

A custom directory set in Zotero is picked up automatically from its preferences, on every platform. bin/zotero-mcp status reports which of these it used.

The two sources

Every read tool takes a source argument.

local (default) — reads zotero.sqlite from your Zotero data directory. Fast, works offline, works whether or not Zotero is running, and is the only source that can return PDF file paths.

Zotero holds an exclusive lock on that file while it runs, so the server reads from a snapshot copy under ~/.cache/zotero-mcp/, refreshed automatically whenever the live database changes. Nothing is ever written to your Zotero data.

web — api.zotero.org with your API key. Needed for group libraries, for items that have not synced to this machine, for real CSL citation formatting, and for the two write tools.

Configuration

Everything is autodetected except the API key. The Zotero data directory and your numeric user ID are read from Zotero's own profile, so for local-only use there is nothing to configure.

To add a web API key — create one at https://www.zotero.org/settings/keys/new, then:

bin/zotero-mcp setup                    # prompts, hiding the key as you type
bin/zotero-mcp setup --key=... --user-id=...   # or non-interactively

The prompt hides the key as you type and writes ~/.config/zotero-mcp/config.json with mode 600. Every field is optional:

{
  "api_key": "...",
  "user_id": "YOUR_NUMERIC_USER_ID",
  "data_dir": "~/Zotero",
  "library_type": "user",
  "default_source": "local"
}

Environment variables override the file: ZOTERO_API_KEY, ZOTERO_USER_ID, ZOTERO_DATA_DIR, ZOTERO_BASE_ATTACHMENT_PATH, ZOTERO_LIBRARY_TYPE, ZOTERO_DEFAULT_SOURCE.

Give the key read/write permission if you want zotero_create_item and zotero_add_note to work; read-only is fine for everything else.

Tools

CLI

Useful for checking things without going through Claude:

bin/zotero-mcp status                              # diagnostics
bin/zotero-mcp setup                               # store API key / user ID
bin/zotero-mcp tools                               # list tools
bin/zotero-mcp tool zotero_search '{"query":"x"}'  # run one tool
bin/zotero-mcp                                     # serve over stdio (what Claude runs)

Privacy

Your library never leaves your machine unless you use source: "web", which talks to zotero.org and nowhere else. There is no telemetry and no third-party network code — the only outbound requests in the codebase are to api.zotero.org.

The API key is stored only in ~/.config/zotero-mcp/config.json (mode 600), never in the repository, and is never logged.

How the local backend works

It queries Zotero's SQLite tables directly (items, itemData, itemCreators, collections, itemTags, itemAttachments, itemNotes) and uses the FTS5 index in fulltext.sqlite for full-text search.

That schema is a Zotero implementation detail and can change between releases. The code is written against userdata schema v129 (Zotero 7); on a newer schema it prints a note to stderr and keeps going, rather than failing. Since every local query is read-only against a snapshot copy, a schema change can at worst produce wrong output — never a damaged library.

Zotero's own HTTP local API (localhost:23119/api, off by default) is not used; reading the database directly works whether or not it is enabled.

Troubleshooting

"Zotero database not found" — run bin/zotero-mcp setup --data-dir=/your/path. Find the real path in Zotero under Settings -> Advanced -> Files and Folders. bin/zotero-mcp status shows where it looked and why.

Claude does not see the tools — restart Claude Code, then check claude mcp list.

Attachment shows FILE MISSING — the item's file has not synced to this machine yet; open it once in Zotero, or use source: "web".

Full-text search finds nothing — only attachments Zotero has indexed are searchable. Check Settings → Search in Zotero.

License

MIT — see LICENSE.

Not affiliated with, endorsed by, or supported by Zotero (Corporation for Digital Scholarship) or Anthropic. "Zotero" and "Claude" are their respective trademarks, used here only to describe what this tool connects.