Zoteus

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

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.

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. Your own notes and PDF annotations are indexed too, under the item they hang off, so "where did I object to this?" is a question search can answer. Turn on ZOTEUS_INDEX_FULLTEXT (or pass fulltext:true to zotero_index) and semantic search covers the body of every PDF too, so a claim that never made it into an abstract is still findable.
• 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. Quote the passage and it is located in the PDF and anchored to the exact lines it occupies, wrapping and hyphenation included, so highlighting takes no page coordinates. 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 or the EPUB, straight from the running desktop app or from Zotero's own storage folder, so a file added a minute ago is readable immediately. It also reads a PDF's table of contents (outline:true) and any page range on demand, so working through a 400-page book costs two small calls rather than one that returns the book.
• 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, 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. That covers your personal library and, on Zotero 10+, any group library the app holds; a key is needed when the app is closed, and for a group the app does not hold.

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 (the resolved dependency tree, onnxruntime's native binaries included, is about 700 MB): install it into a directory of its own (mkdir -p ~/.zoteus-deps && cd ~/.zoteus-deps && npm init -y && npm i @huggingface/transformers) and set ZOTEUS_TRANSFORMERS_PATH to ~/.zoteus-deps/node_modules. Not npm i -g: Claude Desktop runs the server on its own built-in Node, so a global install under a version manager sits next to a Node the extension never executes. 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

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.