⚡ 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 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

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.

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 9+ that's the local API behind a key you grant once ("Always Allow"); on older builds 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

1. Install — one npx command (or the one-click .mcpb).
2. Connect — just run the desktop app for key-free local access, or paste your Zotero API key.
3. 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), 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.

Configuration

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

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.