Search, read, annotate, and add to your Zotero research library, local or web.
This MCP server supports interacting with a Zotero research library to search, read, annotate, and add items from local or web sources. It is positioned for use with tools and clients such as Claude and ChatGPT, based on the provided documentation excerpt.
🛠️ Key Features
Search within a Zotero research library
Read library items
Annotate items
Add items to Zotero
Works with local or web content
🚀 Use Cases
Finding references in a Zotero library for research
Zotero MCP: Chat with your Research Library in Claude, ChatGPT, and more
Your Zotero library, in every AI agent.
Search, read, cite and annotate your papers from Claude, ChatGPT, Codex, Cursor, or a chat panel inside Zotero.
Zotero Agent explaining a paper with page citations. A click on a citation opens the page and flashes the cited sentence.
Zotero MCP connects your Zotero research library with ChatGPT, Claude, and other AI assistants (e.g., Cherry Studio, Chorus, Cursor) via the Model Context Protocol. Search your library, read and annotate papers, add and organize items, and find research by meaning.
AI agents: read docs/for-agents.md first. It covers which route to use, setup, and the commands in one place.
Three ways in
One package, zotero-mcp-server, ships all three. Pick the one that fits where you work.
MCP server
zotero-cli + agent skill
Zotero Agent
For
Chat apps that speak MCP but have no shell: Claude Desktop, ChatGPT, Cherry Studio, Chorus
Agents with a shell: Claude Code, Codex, Cursor, Windsurf, Gemini CLI, Amp, OpenCode
Chatting inside Zotero, next to the PDF you are reading
How
zotero-mcp setup
zotero-mcp install-skill
zotero-cli plugin, then install the .xpi in Zotero
Why
Works in any MCP client
98 tokens in context until it is needed, instead of ~8k
Knows the item, page and selection you have open; answers link to pages
New to the command line? Try the community-built Zotero MCP Setup: a macOS GUI installer, one-click scripts for Mac and Windows, and a step-by-step guide.
2. Enable Zotero's local API: in Zotero 7+, open Settings → Advanced and tick Allow other applications on this computer to communicate with Zotero.
3. Connect your assistant:
Claude Desktop
bash
zotero-mcp setup # auto-configures Claude Desktop
or add the server by hand to claude_desktop_config.json:
zotero-cli plugin # where the .xpi is, and how to install it
Then in Zotero: Tools > Plugins, the gear, Install Plugin From File. Details: Zotero Agent plugin.
4. Writes (optional): on Zotero 10+, run zotero-mcp authorize-local once and choose Always Allow. On older Zotero, add ZOTERO_API_KEY and ZOTERO_LIBRARY_ID to write through the web API.
Then ask things like "Find papers in my library on attention mechanisms", "Summarize the key findings of this paper", or "Highlight the main claims of this PDF".
Optional extras
The base install covers search, reading, annotations, and writes. Heavier features are extras:
Extra
What it adds
Install command
semantic
Semantic search via ChromaDB, sentence-transformers, OpenAI/Gemini embeddings
pip install "zotero-mcp-server[semantic]"
pdf
PDF outlines, page layout and page images (PyMuPDF), EPUB annotations
pip install "zotero-mcp-server[pdf]"
scite
Scite citation tallies and retraction alerts (no account needed)
pip install "zotero-mcp-server[scite]"
all
Everything above
pip install "zotero-mcp-server[all]"
Update any time with zotero-mcp update.
MCP server or agent skill?
If your agent has a shell (Claude Code, Cursor, Codex, Windsurf, Gemini CLI, Amp, OpenCode …), one command teaches it to drive zotero-cli:
bash
zotero-mcp install-skill
An MCP server sends every tool's schema on every request, before you type anything. The skill costs 98 tokens until the agent decides it is relevant:
Route
In context
Paid
MCP server, default profile (38 tools)
7,939
every request
MCP server, all tools (50)
11,225
every request
Agent skill, frontmatter only
98
always
Agent skill, body loaded
2,400
when it fires
Agent skill + full command reference
6,582
worst case
Use the MCP server when your client speaks MCP but has no shell (Claude Desktop, ChatGPT); use the skill when it has a shell. Both share one config. Details: CLI and agent skill.
Zotero Agent: chat inside Zotero
A plugin that adds a chat panel to Zotero itself, driven by your own Claude Code, Codex or pi. It knows which item and page you have open and works your library through zotero-cli. Answers cite papers with real zotero:// links, so a click opens the PDF at that page. It ships in the wheel: run zotero-cli plugin for the file and the install steps, or paste the one-paragraph prompt in the docs to your agent and let it do the setup. Details: Zotero Agent plugin.
Issues and pull requests are welcome. Run the tests with uv run pytest tests/. A live integration test plan, meant to be run by Claude against a real library, is in docs/integration-test-plan.md. Changes to the plugin in plugin/ (AGPL-3.0) are accepted on the condition that the maintainer may also release them under other terms, including commercial ones.
Thanks to everyone who has contributed code, fixes, and ideas to Zotero MCP.
Support
Zotero MCP is free and open source.
If it saves you or your lab time, sponsoring helps cover the unglamorous parts: Windows and WSL2 edge
cases, Zotero schema changes, group-library support, and the embedding/search infrastructure.
Labs and institutions: the $50 and $200 tiers are meant to be expensable, and include priority
triage on the issues affecting your workflow.
License
The MCP server and zotero-cli are MIT (LICENSE). The Zotero Agent plugin in plugin/ is AGPL-3.0-or-later (plugin/LICENSE), the license Zotero itself uses.
Install
Configuration
Environment variables
ZOTERO_LOCALdefault true
Read from the local Zotero desktop app instead of the web API. Requires Zotero 7+ with the local API enabled in Settings > Advanced.
ZOTERO_API_KEYsecret
Zotero Web API key from https://www.zotero.org/settings/keys. Only needed when ZOTERO_LOCAL is false, or for write operations in hybrid mode.
ZOTERO_LIBRARY_ID
Zotero user or group library ID. Only needed when ZOTERO_LOCAL is false, or for write operations in hybrid mode.
ZOTERO_LIBRARY_TYPEdefault user
Whether ZOTERO_LIBRARY_ID refers to a personal or a group library.
ZOTERO_MCP_TOOLSETS
Which optional tool groups to expose, as a comma-separated list. Every tool is sent to the model on each request, so optional capabilities are off by default. Use 'all' for the full surface, 'none' for core only, 'default' for the default profile, named groups (scite, duplicates, discovery, feeds, relations, libraries, search-admin, pdf-geometry, legacy) to add them, or a leading '-' to subtract. 'legacy' brings back tool names merged in 0.16 (until 0.17).