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 library's metadata and abstracts, pull exact passages from your PDFs, and ground every answer in a source you actually own. Local-first. Private. One command.

npx -y @oscardvs/zoteus

Install in 30 seconds

For normal use there is nothing to download or unzip from GitHub — your AI app fetches Zoteus automatically when it first runs. New to this? Follow the no-code getting-started guide → docs/getting-started.md

Client	Command
Claude Desktop (one-click)	download `zoteus.mcpb` from the latest release → double-click
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.ai (web)	Add custom connector → your hosted URL (OAuth)

Updating a desktop-extension install: manually installed extensions (.mcpb, or the older .dxt) do not auto-update. Zoteus checks GitHub releases once a day and tells you in-chat (via zotero_whoami) when a newer version exists; download the new zoteus.mcpb and reinstall it to upgrade. npx installs always run the latest published version.

Add your cloud key for sync, group libraries, and writes without the desktop app (optional — reads and personal-library writes work key-free against a running Zotero):

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 and writes, 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 + full-text PDF retrieval	✅	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 over your library's titles, abstracts, creators, and tags, plus full-text keyword search inside your PDFs and notes, with the matching passage 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 or arXiv id and Zoteus fetches the metadata and files it — works out of the box via built-in resolvers, no extra services needed (a Zotero translation-server extends this to ISBN/PMID/URLs; see docs/resolver.md).
Write back, safely. Create items, edit, tag, organize — versioned with optimistic-locking retries, reversible trash by default, permanent delete opt-in and confirmation-gated.
Write straight to the desktop app. Personal-library writes go to your running Zotero — no cloud API key needed. On Zotero 10+ that's the local API behind a key you grant once ("Always Allow"); on Zotero 9 and earlier, whose local API is read-only, it's the same connector protocol the browser extensions use. The cloud Web API is the fallback for group libraries and for when the app isn't running.
Annotate PDFs and attach files. zotero_annotate adds real highlights, underlines, and notes — the same objects the Zotero PDF reader creates, positioned on the page — and zotero_attach_file stores a local file or a URL as an attachment under any item.
Ground claims in the PDF. zotero_get_fulltext returns the relevant passage with character offsets, nearest heading, and a page locator — extracting the text on the fly when Zotero hasn't indexed the PDF.
Follow the scholarship. A scholarly-context graph over OpenAlex / Crossref / Semantic Scholar.
Built for agents. 30 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 npx command (or the one-click .mcpb).
Connect — just run the desktop app for key-free local access, or paste your Zotero API key.
Ask — your AI can now search, cite, add, and organize your library.

Zoteus auto-detects your running Zotero desktop app and talks to it directly: its fast, key-free local API for reads (full PDFs, real saved-search results, the semantic-search index build), and the desktop app itself for personal-library writes (imports, annotations, attachments, trash). The cloud Web API v3 is the fallback — and stays required for sync, group libraries, and writes when the app isn't running. Details: docs/writing.md.

Semantic search — one-time setup. The first zotero_semantic_search builds the library index automatically in the background (auto-build). On very large libraries you can also run zotero_index (action:"build") yourself, then poll action:"status" until done. The build pages your library through the same local-first path as every other read, so it needs no cloud API key while the desktop app is running — a key is only needed when the app is closed, and always for group libraries.

Vector ranking is opt-in. Keyword (BM25) search works out of the box everywhere. On-device vectors need @huggingface/transformers, which the desktop-extension bundle cannot ship (onnxruntime's native binaries run to ~380 MB across platforms): install it with npm i -g @huggingface/transformers and set ZOTEUS_TRANSFORMERS_PATH to the directory npm root -g prints. When vectors are unavailable Zoteus says so in zotero_index status, zotero_whoami, and zotero_semantic_search rather than quietly returning nothing. See docs/semantic-search.md.

Configuration

Variable	Default	Purpose
`ZOTERO_API_KEY`	—	Cloud auth (sync, groups, writes without the desktop app; optional otherwise)
`ZOTEUS_LOCAL`	`auto`	`auto\|on\|off` — use the Zotero desktop app (reads + personal-library writes)
`ZOTEUS_LOCAL_API_KEY`	—	Pre-provision the Zotero 10+ desktop write key (else granted once, in-app)
`ZOTEUS_EMBEDDINGS`	`local`	`local\|openai\|gemini\|off` for semantic search
`ZOTEUS_TRANSFORMERS_PATH`	—	Where to find `@huggingface/transformers` for `local` embeddings when the install can't see it (desktop extension)
`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 · Getting started · Configuration · Import & resolver · Architecture · Safe writes · Citations · Semantic search · Scholarly context · Code execution · Deployment

Privacy Policy

Zoteus runs locally, collects nothing, and has no telemetry. Your library data flows only between your machine and the services you configure (Zotero, and optionally scholarly-graph or embedding providers), directly and under your own keys. Full policy: PRIVACY.md.

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.