@oscardvs/zoteus

⚡ 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_fulltext returns 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 npx command (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.