⚡ Zoteus
Your Zotero library, inside every AI conversation — with real citations, not hallucinations.
The everything Zotero MCP server. Give Claude, Cursor, and any MCP client complete, safe access to your Zotero library — search papers, add by DOI, format bibliographies in ~2,800 styles, run semantic search over your own PDFs, and ground every answer in a source you actually own. Local-first. Private. One command.
npx -y @oscardvs/zoteus
Install in 30 seconds
| Client | Command |
|---|---|
| Claude Code | claude mcp add --transport stdio zoteus -- npx -y @oscardvs/zoteus |
| Cursor / VS Code / Claude Desktop / Codex / Zed… | npx add-mcp @oscardvs/zoteus |
| Claude Desktop (one-click) | download zoteus.mcpb from the latest release → double-click |
| claude.ai (web) | Add custom connector → your hosted URL (OAuth) |
Add your cloud key for writes/sync/groups (optional — reads work key-free against the desktop app):
claude mcp add --transport stdio zoteus -e ZOTERO_API_KEY=xxxxx -- npx -y @oscardvs/zoteus
Get a key at zotero.org/settings/keys. For key-free local reads, enable Settings → Advanced → "Allow other applications on this computer to communicate with Zotero" in the desktop app.
Why Zoteus?
There are several Zotero MCP servers now. Zoteus is the one that does everything — and adds the parts everyone else skips. The difference that matters: Zoteus treats your library as the source of truth, not a search index. When you ask Claude to "draft a methods paragraph citing the five most relevant papers in my collection," it runs that against your verified, already-curated references — no invented citations, no Python stack, nothing leaves your machine.
| Zoteus | Other Zotero MCP servers | Web AI (Elicit/SciSpace) | |
|---|---|---|---|
| Operates on your own library | ✅ | ✅ (varies) | ❌ (web-wide) |
| Complete Web API v3 + desktop local API | ✅ | partial | n/a |
| Safe transactional writes (reversible, gated) | ✅ | rare | ❌ |
| CSL bibliographies (~2,800 styles) | ✅ | rare | ❌ |
| Local hybrid semantic search over PDFs | ✅ | some (cloud) | varies |
No Python — TypeScript, one npx | ✅ | varies | n/a |
| MCP Resources + Prompts + code-execution | ✅ | ❌ | n/a |
| Local-first / private · Open-source (MIT) | ✅ | varies | ❌ |
What you can do
- Find anything in your own work. "Find papers in my library that argue against X" — hybrid keyword + semantic search across metadata, full text, and annotations, returned with the page number.
- Cite without hallucinating. Zoteus surfaces your Zotero citation data and formats it with citeproc-js in any CSL style — it never invents a reference.
- Add a paper by identifier. Drop in a DOI/ISBN/PMID/arXiv id and Zoteus fetches the metadata and files it — no account needed for the import → format path.
- Write back, safely. Create items, edit, tag, organize — versioned with optimistic-locking retries, reversible trash by default, permanent delete opt-in and confirmation-gated.
- Ground claims in the PDF.
zotero_get_fulltextreturns the relevant passage with character offsets, nearest heading, and a page locator. - Follow the scholarship. A scholarly-context graph over OpenAlex / Crossref / Semantic Scholar.
- Built for agents. ~28 consolidated, well-described tools (not 70 thin endpoint mirrors),
zotero_*-namespaced, structured outputs, and a generated tool tree for the code-execution-with-MCP pattern.
How it works
- Install — one
npxcommand (or the one-click.mcpb). - Connect — paste your Zotero API key (or just run the desktop app for key-free local reads).
- Ask — your AI can now search, cite, add, and organize your library.
Zoteus auto-detects your running Zotero desktop app and uses its fast, key-free local API for reads (full PDFs, real saved-search results), falling back to the cloud Web API v3 for writes, sync, and group libraries.
Configuration
| Variable | Default | Purpose |
|---|---|---|
ZOTERO_API_KEY | — | Cloud auth (writes/sync/groups; optional for local-only reads) |
ZOTEUS_LOCAL | auto | auto|on|off — use the Zotero desktop local API |
ZOTEUS_EMBEDDINGS | local | local|openai|gemini|off for semantic search |
ZOTEUS_ALLOW_DELETE | false | Must be true to expose permanent deletion |
Full table in docs/configuration.md. Running a shared/remote instance? See docs/remote-oauth.md (self-host the OAuth remote on loopback or behind your own proxy).
Documentation
📚 zoteus.com/docs · Architecture · Safe writes · Citations · Semantic search · Scholarly context · Code execution
Contributing
Contributions welcome — see CONTRIBUTING.md. MIT licensed.
Acknowledgements
Built on the Model Context Protocol, the Zotero Web API, citeproc-js, and the Citation Style Language. Not affiliated with or endorsed by the Corporation for Digital Scholarship / Zotero.