Access your Zotero library with your favorite AI tool.
This MCP server for Zotero 8+ gives Claude and Codex access to your library via search and citekyes. It talks directly to Zotero's local API and aims to keep token usage low. Fulltext is fetched only on demand.
Quick Start
- Make sure Zotero 8+ is running with the local API enabled (Settings → Advanced → "Allow other applications on this computer to communicate with Zotero").
- Install the Claude Code plugin:
/plugin marketplace add statzhero/zotero-fulltext
/plugin install zotero@zotero-fulltext
- Run
/mcp to confirm the server is connected, then try a slash command:
/zotero:find sustainability reporting
Also works with Claude Desktop, Codex, and as a standalone MCP server without slash commands.
Commands
The Claude Code plugin provides four slash commands:
| Command | What it does |
|---|
/zotero:find <query> | Search the whole library |
/zotero:lookup <citekey> | Exact citekey metadata lookup |
/zotero:read <citekey> | Numbered fulltext paragraphs |
/zotero:within <citekey> <query> | Search inside one paper's fulltext |
find searches the whole library. lookup is lightweight metadata confirmation. read returns the actual paper text. within searches only one item's indexed fulltext.
Without the plugin, all the same functionality is available through the MCP tools directly (see Tools).
Installation
Claude Code (plugin with slash commands)
/plugin marketplace add statzhero/zotero-fulltext
/plugin install zotero@zotero-fulltext
This installs the MCP server and slash commands. Run /mcp to confirm the server is connected.
Claude Desktop
Requires uv (install with brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh).
Open Claude Desktop → Settings → Developer → Edit Config, and add:
{
"mcpServers": {
"zotero": {
"type": "stdio",
"command": "uvx",
"args": ["zotero-fulltext"]
}
}
}
Save the file, then fully quit and reopen Claude Desktop (closing the window is not enough). Open a new chat and confirm the server is available.
Codex (plugin with skills)
Note: The Codex plugin marketplace is still rolling out. The install flow below may change.
codex plugin marketplace add statzhero/zotero-fulltext
codex plugin install zotero
This installs the MCP server and four skills (find, lookup, read, within).
Codex (manual MCP only)
Requires uv (install with brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh).
Add to ~/.codex/config.toml:
[mcp_servers.zotero]
command = "uvx"
args = ["zotero-fulltext"]
Restart Codex, then run codex mcp list to verify the server appears.
Design
The server is intentionally simple and read-only. It relies on Zotero's own search index rather than building a second one.
- Startup builds a metadata index mapping citekeys to items and attachments.
- Library changes are tracked with Zotero version headers and incremental sync.
- Fulltext is fetched only on demand and cached in memory (TTL/LRU).
- All outputs are bounded by default: 10 search hits, 80 paragraphs, 20 fulltext matches.
- Item results include
item_uri and fulltext_uri so clients can attach standard zotero://... resources directly.
- If a lookup finds no citekey, it returns
found=false. If a search finds nothing, it returns results=[]. There is no web fallback.
Tools
The server exposes five MCP tools. The slash commands above are convenience wrappers.
lookup(citekey)
Exact citekey lookup. Citekeys are resolved in order:
- Native Zotero 8
citationKey
- Legacy Better BibTeX
Citation Key: line in Extra
- Deterministic generated fallback
If an item later gains a real citekey, the generated key is kept as an alias.
search(query, collection?, tag?, limit?)
Searches Zotero with qmode=everything, collapses attachment hits to parent items, and ranks exact citekey matches first.
collections()
Lists collections in the current library.
fulltext(citekey, offset?, limit?)
Fetches indexed attachment fulltext, splits it into numbered paragraphs, and returns a bounded slice (default: 80 paragraphs).
fulltext_search(citekey, query, before?, after?, limit?)