oscardvs/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.
| Client | How |
|---|---|
| **Claude Desktop** | Download the bundle for your system from the latest release, zoteus-macos.mcpb, zoteus-windows.mcpb or zoteus-linux.mcpb, and double-click it. This is the install with a settings screen (**Settings → Extensions → Zoteus**) and per-tool permissions. |
| **Claude Code** | claude mcp add --transport stdio zoteus -- npx -y @oscardvs/zoteus |
| **Claude Code, as a plugin** | /plugin marketplace add oscardvs/zoteus, then /plugin install zoteus@zoteus. The same server, plus four research skills that teach Claude to quote passages with pages, build evidence tables, cite, and tidy the library. Set the optional API key with /plugin → Zoteus → **Configure options**. Claude Desktop shows no settings for a plugin, so use the .mcpb there. See plugins/zoteus. |
| **Cursor, VS Code, Zed, Codex, Gemini CLI, any MCP client** | npx add-mcp @oscardvs/zoteus, or add npx -y @oscardvs/zoteus as a stdio server by hand. |
| **claude.ai in the browser** | Add a custom connector pointing at a hosted Zoteus or at your own remote instance. |
| **ChatGPT (web)** | Needs Developer mode on a paid ChatGPT plan (**Settings → Security and login**). Then **Plugins → Create app**, with the server URL of a hosted Zoteus (https://mcp.zoteus.com/mcp) or of your own remote instance, and OAuth as the authentication. ChatGPT only connects to remote servers, so the npx install does not apply. |
Then run the Zotero desktop app. Reads, and the personal-library writes that go through the app (adding items by identifier, attachments, annotations, trash and restore), need no cloud key. Add a Zotero API key for sync, group libraries, metadata edits, tags and collections, and for when the app is closed:
> 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 personal-library writes go to it directly and need no cloud API key; the Zotero Web API v3 is the fallback for sync, group libraries, 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.