Zoteus

Zoteus

A Zotero MCP server. Your whole library, inside Claude and ChatGPT.

Zoteus gives Claude Desktop, claude.ai, ChatGPT, Claude Code, Cursor and any other MCP client access to a Zotero library: search by keyword or by meaning, passages from your PDFs with page numbers, citations in any CSL style, adding items, and safe writes.

A real session, 6 September 2026, against the maintainer's own library. Tool calls are shown as a time-lapse. The full recording is on zoteus.com .

Install

For most clients there is nothing to download: the client fetches Zoteus with npx the first time it runs. New to MCP servers? Start with docs/getting-started.md.

Then run the Zotero desktop app. Reads, and on Zotero 10+ writes to every library the app holds (your own and the group libraries synced into it), need no cloud key. Add a Zotero API key for sync, for group libraries the app does not hold, and for when the app is closed:

claude mcp add --transport stdio zoteus -e ZOTERO_API_KEY=xxxxx -- npx -y @oscardvs/zoteus

Get a key at zotero.org/settings/keys. In the desktop app, enable Settings → Advanced → "Allow other applications on this computer to communicate with Zotero". Step-by-step for each client, with screenshots: zoteus.com/docs/connect-claude-to-zotero.

Updating a desktop-extension install. A manually installed .mcpb (or older .dxt) does not auto-update. Turn on Check for updates in the extension settings (or set ZOTEUS_UPDATE_CHECK=true) and Zoteus asks GitHub once a day, then says so in-chat via zotero_whoami when a newer version exists; download the new bundle for your system and reinstall. The check is off by default. npx installs always run the latest published version.

What it does

Zoteus exposes research tools, namespaced zotero_*, that search the library by keyword or by meaning, return passages from your PDFs with page locators, show PDF pages and figures as images, format bibliographies with citeproc-js in any CSL style, add items by DOI or arXiv id, and create, edit, tag and organize items with versioned writes and a reversible trash. When the Zotero desktop app is running, reads and writes go to it directly for every library it holds and need no cloud API key; the Zotero Web API v3 is the fallback for sync, group libraries the app does not hold, and for when the app is closed. Zoteus is written in TypeScript, runs on your machine, and is MIT licensed.

Features

• Search your own library. Hybrid keyword and semantic search over titles, abstracts, creators, and tags, plus full-text keyword search inside your PDFs and notes, with the matching passage returned together with its page number. Your own notes and PDF annotations are indexed under the item they belong to, so "where did I object to this?" is a question search can answer. Set ZOTEUS_INDEX_FULLTEXT (or pass fulltext:true to zotero_index) and indexed search also covers available PDF body text within configured caps, so a claim that never made it into an abstract is still findable.
• Format citations. Zoteus reads the citation data in your Zotero library and formats it with citeproc-js in any CSL style from the CSL styles repository.
• Add a paper by identifier. Pass a DOI or arXiv id and Zoteus fetches the metadata and files the item. This works out of the box through built-in resolvers; a Zotero translation-server extends it to ISBN, PMID, and URLs (see docs/resolver.md).
• Write back. Create items, edit, tag, and organize. Writes are versioned with optimistic-locking retries, trash is reversible by default, and permanent deletion is opt-in and confirmation-gated.
• Write straight to the desktop app. Adding and editing items, tags, collections, saved searches, merges, attachments, annotations, and trash and restore go to your running Zotero with no cloud API key, in your own library and in any group library the app holds. On Zotero 10+ this uses the local API behind a key you grant once ("Always Allow"); on Zotero 9 and earlier, whose local API is read-only, adding items and annotations uses the connector protocol the browser extensions use. The cloud Web API is the fallback for group libraries the app does not hold, and for when the app is not running.
• Annotate PDFs and attach files. zotero_annotate adds highlights, underlines, and notes, the same objects the Zotero PDF reader creates. Quote the passage and Zoteus locates it in the PDF and anchors the annotation to the lines it occupies, wrapping and hyphenation included, so no page coordinates are needed. zotero_attach_file stores a local file or a URL as an attachment under any item.
• Write notes and digest your annotations. zotero_create_note, zotero_append_to_note and zotero_replace_note write Zotero notes from Markdown (headings, lists, tables, code, math), and turn [@ITEMKEY, p. 12] into real Zotero citations that open the paper and become live fields in Word. zotero_annotation_digest lists the highlights, comments, colours and tags on a paper or a whole collection, read-only, and zotero_save_annotation_digest saves them as a note laid out like Zotero's own "Add Note from Annotations", each highlight still linked to its spot in the PDF (docs/notes.md).
• Ground claims in the PDF. zotero_get_fulltext returns the relevant passage with character offsets, the nearest heading, and a page locator. When Zotero has not indexed the PDF or EPUB, it extracts the text on the fly, from the running desktop app or from Zotero's own storage folder, so a file added a minute ago is readable immediately. It also returns a PDF's table of contents (outline:true) and any page range on demand, so working through a 400-page book costs a few small calls rather than one that returns the whole book.
• Look at the page. zotero_pdf_images renders any page of a PDF to an image the model can see, so a figure, a table, an equation, or a scanned page with no text layer is no longer out of reach, and extracts the figures embedded in a page, like pdfimages, each with its position on the page. It draws through the same pdfjs that reads the text, so it needs nothing that is not already installed.
• Follow the literature. zotero_scholar looks up a paper's references, citing works, and related works through OpenAlex, with Crossref as a fallback, and can flag which of them are already in your library.
• Import a bibliography, find duplicates, merge them. zotero_import reads BibTeX, RIS and CSL-JSON as text or a file without a translation-server, recovers a DOI or arXiv id from a PDF's first pages, and can check the library for an existing copy before saving. zotero_merge_items folds duplicates into one record: it previews by default, fills only what the master lacks, unions tags, collections and relations, reparents notes and attachments, and trashes the emptied copies (see docs/importing-bibliographies.md, docs/duplicates-and-merging.md).
• Open-access copies and retraction notices. zotero_scholar reports an open-access PDF when OpenAlex knows one and zotero_attach_file can fetch and attach it from the DOI, recording which version it is; zotero_scholar also reports retraction and correction records from Crossref and OpenAlex, as records rather than a verdict (docs/open-access-pdfs.md, docs/retraction-notices.md).
• Evidence tables and Word documents. A zotero-evidence-table prompt plus zotero_evidence_table render gathered passages as a Markdown or CSV table whose quotations cannot drift from the passage they cite, and zotero_word_document writes a .docx whose citations are live Zotero field codes (docs/evidence-tables.md, docs/word-documents.md; refreshing the fields in Word is not yet verified).
• Scans, several libraries, local embeddings. zotero_get_fulltext reads a PDF with no text layer through an optional OCR engine (docs/ocr.md); one data directory holds one search index per library and zotero_semantic_search can search several at once (docs/multiple-library-indexes.md); and ZOTEUS_EMBEDDINGS=ollama embeds through a local Ollama daemon with no API key (docs/ollama.md). zoteus index build runs a headless index build from the command line.
• Agent support. 39 tools with structured outputs, MCP Resources and Prompts, and a generated tool tree for the code-execution-with-MCP pattern.

How it works

1. Install with one npx command, or the one-click .mcpb.
2. Connect by running the desktop app for key-free local access, or by pasting your Zotero API key.
3. Ask. Your MCP client can now