0.14.0Zotero Agent: your own AI agent, inside Zotero

Chat with your research library in Claude, ChatGPT, and more.

Zotero MCP connects your Zotero library to AI assistants. Search it, read it, annotate it, and add to it, from the desktop app or the web API.

$ uv tool install zotero-mcp-server
$ zotero-mcp setup
Python 3.10+Zotero 7+MIT licensed
New · Zotero Agent

Your own AI agent, inside Zotero

A chat panel next to the PDF you are reading, on the Claude Code, Codex or pi you already use. It knows the page you are on, cites the sentence, translates in the reader and saves answers as notes. No extra API key.

Recent releases

What’s new

0.17.2Nov 2026

Annotation tools for the CLI, and named chats

zotero-cli can now move a box in place (annotations update --rect), list where each annotation is stored (list --positions), draw the stored annotations on page images (annotations preview, and batch --dry-run --render for a plan before anything is written), re-run a batch without duplicating it (--on-existing), split a figure into panels, grid a page image, and say which nearby text it found when a highlight’s words are not in the PDF. add doi --attach-file adds a paper and attaches your own PDF in one call, and add folder does it for a folder of PDFs.

Zotero Agent chats are named, by the agent’s own summary, the paper you had open or your first question, and you can rename them. Whether sending a message scrolls to the newest one is a setting now. python -m zotero_mcp starts the CLI without the .exe launcher that Windows Smart App Control can block, and ZOTERO_ONNX_THREADS quiets the thread-pinning errors of the default embedding model in containers.

With fixes from @HelloNVIC (#836, #847), @lots-o (#828) and @fgndh89-commits (#837).

0.17.1Nov 2026

OpenCode in the panel, and Mermaid diagrams

The Zotero Agent panel runs OpenCode as a built-in agent next to Claude Code, Codex and pi, on OpenCode’s free models or your own providers, with no bridge or Node.js to install. Mermaid flowcharts and sequence diagrams in an answer are drawn as figures in the panel’s own style, in light and dark, and can be saved to a note. On Windows, Claude Code installed through npm starts again instead of failing with spawn EINVAL.

Batch embeddings (OpenAI and Gemini) now index passages too, ending in the same index a realtime update builds. If you already had chunking and batch both on, your next update-db embeds passages for the whole library, and the provider bills for it. zotero-mcp setup asks for your WebDAV settings in web mode and keeps them on a re-run, and copied items’ files go to WebDAV as well.

With fixes from @mronkko (#819), @ShoRoy (#820), @FFXFF1 (#827), @goranai (#818) and @kskszq (#821, #822), and requests from @HelloNVIC (#823, #824).

0.17.0Nov 2026

Articles and passages apart, and the panel in your language

The semantic index now keeps one record per article and the passages of each paper in separate collections. An article search no longer has to load every passage, turning chunking on no longer needs a rebuild, and zotero_semantic_search(level="articles"|"passages") picks the level. An index built with chunking on keeps working as it is; zotero-mcp migrate-index splits it when you choose to, renaming the passages and embedding nothing until the next update. Automatic updates never fill passages for the whole library on their own: that waits for an update-db you run, so a paid embedding API is not billed unasked.

The Zotero Agent panel speaks Chinese (simplified and traditional), Japanese, German, French, Spanish and Brazilian Portuguese, following Zotero’s own language unless you pick one, and in Zotero’s own words for items, collections and annotations. You can run your own ACP agent next to Claude Code, Codex and pi, Codex chats use your installed Codex when it is newer than the bridge’s, and the top bar lines up with the reader toolbar. Items can be copied between libraries (opt-in), Zotero’s retraction flags show up in item metadata, exported bibliographies show & instead of &, and scanned PDFs whose OCR text sits under a visible stamp read correctly.

Translations other than Chinese are marked beta; corrections from native speakers are welcome. With fixes from @mronkko (#561, #786 to #792, #795), @danmackinlay (#507, #509), @FFXFF1 (#729) and @kskszq (#809, #813), and the diagnosis of #811 from @liuup.

0.16.0Nov 2026

Half the context, faster batch edits, and auth for HTTP

The MCP server’s default tools now cost about 8k tokens per request instead of 17k. Descriptions are rewritten to what an agent needs to pick the tool, schemas are compact, and a test keeps the total from creeping back. zotero_search_items takes tags directly and zotero_manage_collection replaces three collection tools; the old names stay available for one release with ZOTERO_MCP_TOOLSETS=default,legacy. zotero_add_item now reuses an item it already has instead of adding a duplicate.

Batch tag and Extra edits take about 40 requests for 1000 items instead of 2000, and zotero-cli commands start in under half the time. In local mode more reads come straight from zotero.sqlite: whole-library annotations and notes, page layouts, the duplicate scan (no 5,000 item cap) and the Scite tools. The HTTP transports take a bearer token (ZOTERO_MCP_AUTH_TOKEN) and refuse to listen on the network without one. Semantic search notes when the index is behind the library, stops cleanly when the embedding API can’t be reached, and no longer submits the same Batch API changes twice. In the Zotero Agent panel, a resized area now sends the new picture.

Tool names changed: if a client or prompt calls zotero_search_by_tag or the collection tools by name, switch to the new ones or turn on the legacy group. With fixes from @mronkko (#770 to #775, #777, #779 to #781, #783), @iamnotmili (#643), @kskszq (#762 to #765), @mirinae3145 (#778), @ppcvote (#767), @shpigunov (#784, #805), @ShoRoy (#806), @Winston-9527 (#797) and @6801318d8d (#800, #801).

0.15.0Oct 2026

Windows fixes, and full PDFs from repositories

On Windows, Claude Desktop no longer shuts the server down at startup when the semantic index updates on start: the update now runs as a separate process, so the server answers right away. The Zotero Agent plugin now finds Claude Code, Codex and pi on Windows, and installed copies update themselves. Translating with pi is not available there yet. Windows support for the plugin is new, so reports on #700 help.

Adding a paper by DOI now also tries the repository copies OpenAlex lists, after Unpaywall and before the publisher’s page, and a publisher PDF that is only a short preview is skipped for the next source. Semantic search is its own tool group, on by default and left out when the [semantic] extra isn’t installed; ZOTERO_MCP_TOOLSETS=none now leaves it out too, so use none,semantic to keep it. In local mode the duplicate check reads the DOI from zotero.sqlite, so a batch import no longer holds Zotero at full CPU for minutes. Markdown and YAML files can be attached, and their text is indexed.

If you built an index with gemini-embedding-2, rebuild it with update-db --force-rebuild: it stored one vector per batch instead of one per item. With fixes from @phil-c137 (#708), @mronkko (#705), @falcon1-1-code (#689, #693 to #695), @lots-o (#698, #699), @RizgarOzan (#696) and @kskszq (#707).

0.14.1Oct 2026

Fixes for Windows, annotations and snapshots

On Windows the index update lock now works, so two servers no longer both index, and setup and zotero-cli no longer crash on a console that cannot show emoji or Chinese; setup also finds the Microsoft Store build of Claude Desktop. The index can live anywhere with semantic_search.persist_directory, which helps a Windows home folder with non-ASCII characters. Created annotations sort in reading order, Voyage embeddings send input_type, web snapshots drop empty table scaffolding and convert deeply nested pages, and update-db no longer indexes annotations as documents.

With fixes from @lots-o (#685), @sghng (#684), @dnlfis42 (#609), @MohammadHijjawi97 (#607), @RizgarOzan (#615) and @falcon1-1-code (#687, #688).

0.14.0Oct 2026

Zotero Agent: your own agent, inside Zotero

A new Zotero plugin puts Claude Code, Codex or pi in a panel next to the PDF you are reading. It knows the item, the page and your selection, cites pages with links that flash the sentence, translates in the reader, and saves answers as notes, all on your own subscription. Install it with zotero-cli plugin; it updates itself. See Zotero Agent.

Also new: zotero-cli read --find and zotero-cli open, notes written in Markdown, case- and accent-insensitive search in SQLite mode, advanced_search on any field from SQLite, whole collections in export_bibliography, PDFs parsed once for repeated page reads, and a faster update-db. The plugin is AGPL-3.0, like Zotero; everything else stays MIT.

With fixes from @falcon1-1-code (#671 to #682), @lipaopao000 (#669) and @feiiiiii5 (#596, #600).

0.13.3Oct 2026

A guard for HTTP, and imports that keep every author

Served over streamable-http or sse, the server used to accept any Host and Origin, so a web page could rebind its hostname to 127.0.0.1 and call every tool from your browser. serve now checks both: on a loopback bind, requests must name localhost and come from no origin or a local one. Clients that connect to localhost, including through mcp-remote, are unaffected. A tunnel or reverse proxy that forwards its own hostname needs it in FASTMCP_HTTP_ALLOWED_HOSTS; the server says so on start-up.

BibTeX imports keep every author when the list wraps across lines, CSL JSON keeps “van der” and “Jr.”, and a book chapter added by DOI keeps its book title. Merging duplicates no longer trashes the highlights on a duplicate’s PDF, index bookkeeping no longer wipes config.json after a hand edit, and PDF downloads stop at 500 MB or 300 s. Stopped servers no longer leave copies of the library in the temp directory, linked files resolve against the right Zotero profile, and embeddings work with Voyage AI through the openai provider.

With fixes from @falcon1-1-code (#649 to #659, #666), @feiiiiii5 (#594, #602) and @sghng (#667).

0.13.2Oct 2026

Fixes for merges, re-indexing, and duplicates

Two data-loss bugs are fixed. zotero_merge_duplicates no longer sends distinct linked-file PDFs to the Trash along with the duplicate, and zotero_update_item keeps type-specific fields when the item type changes, so a journal article turned into a conference paper moves publicationTitle to proceedingsTitle. A failed re-embed no longer deletes an item’s passages, and PDFs with a scanner OCR text layer are indexed instead of being treated as metadata only.

Duplicate detection now matches DOIs in canonical form and folds titles the way Zotero does, and percent-encoded doi.org URLs are read as the DOI they name. File uploads into a group library no longer go to your personal WebDAV. Automatic tags stay automatic, bibliographies are numbered 1 to N, a read right after a write sees the write in local mode, and zotero_switch_library accepts the personal library’s listed id.

0.13.1Sep 2026

Sticky notes, and related papers that add up

Annotations can now be sticky notes. zotero_create_annotation takes note=[x, y], zotero-cli annotations create takes --note x,y, and batch plans accept {"page", "note", "comment"}. The note is a 22 pt square centered on that point, the same geometry Zotero’s reader uses, and its text is the comment.

zotero_find_related_papers no longer comes up short without saying so. References that OpenAlex no longer resolves are back-filled, so asking for 20 returns 20, a failed lookup is reported instead of shown as zero, and citing papers are sorted most-cited first. Area boxes land in the right place on rotated pages, update-db progress lines no longer garble the terminal on CJK titles, and a failed search hidden behind a page of notes is reported as an error.

0.13.0Sep 2026

FastMCP 4, and tool messages that arrive

The server runs on FastMCP 4. Over HTTP it answers the MCP 2026-07-28 server/discover handshake that the ChatGPT Secure MCP Tunnel sends, and clients that still use initialize keep working.

Progress and error messages from the tools now reach the client. The tools are synchronous while FastMCP’s log calls are coroutines, so those messages were dropped before. zotero_add_item_relation and zotero_remove_item_relation no longer fail after writing the forward relation, and the MCP serverInfo reports zotero-mcp’s own version.

0.12.5Sep 2026

Search finds the titles it used to miss

Keyword search on the SQLite backend looked up the title, date and journal by a fixed field id, so cases, statutes, webpages and some upgraded databases were skipped or listed as “Untitled”. Fields are now resolved per item type, the way Zotero does it, and the lookup costs less than the old one.

Collection-scoped search works again on the web API, annotations show their own text instead of “Untitled”, zotero_find_related_papers reports citation counts again, and BibTeX export works. update-db --limit no longer marks the whole library as indexed, and the ChatGPT connector falls back to keyword search when there is no semantic index.

Keyword search
1.3 msbefore: 3.6 ms

Measured on a 700-item library. If you have run update-db --limit, run update-db --fulltext once to repair the index.

0.12.4Sep 2026

Read and annotate a paper end to end

Reads flag the equations, figures and tables that text extraction garbles, and can return the page as an image. Highlights land on exactly the words asked for, and a whole reading plan is written in one batch.

37 annotations
2.3 sbefore: 58 s
Layout, per page
24–44 msbefore: 70–110 ms

Measured on “Attention Is All You Need” and two math-heavy papers, Zotero 10 local API.

0.12Sep 2026

Local reads come straight from zotero.sqlite

No more paging through the Zotero API in local mode.

One item
0.4 msAPI: 43.5 ms
Children of 25 items
1.8 msAPI: 2,476 ms
All tags
110 msAPI: 103.9 s

Measured on a 44,105-item library.

0.11Aug 2026

Local writes on Zotero 10, and search across every library

0.10Aug 2026

An agent skill, and JSON output from zotero-cli

0.9Aug 2026

Fifteen tools merged into six

Full changelog

Three ways in

An MCP server, a skill for agents, or a panel in Zotero

One package, zotero-mcp-server, ships all three, with the same config. Pick the one that fits where you work.

MCP server

For chat apps
  • Claude Desktop
  • ChatGPT
  • Cherry Studio
  • Chorus
  • Any MCP client

Your assistant gets Zotero tools for search, reading, annotations, and writes. Runs over stdio, or streamable HTTP for web clients.

$ zotero-mcp setup

Agent skill + zotero-cli

For coding agents
  • Claude Code
  • Cursor
  • Codex
  • Windsurf
  • Gemini CLI
  • Amp
  • OpenCode

The agent runs zotero-cli commands with --json. Its instructions only load when the task involves Zotero.

$ zotero-mcp install-skill

Zotero Agent

For reading in Zotero
  • Claude Code
  • Codex
  • pi

A chat panel next to the PDF. It knows the item, page and selection you have open, and answers link to the page.

What it does →
$ zotero-cli plugin

Context used before you type anything

An MCP server sends every tool’s schema with every request. A skill costs 98 tokens until it’s used.

  • MCP, all tools51 tools, every request11,331
  • MCP, default tools38 tools, every request8,037
  • Skill, instructions loadedonly when it’s used2,787
  • Skill, description onlyalways98

Tokens (cl100k_base), measured with scripts/measure_context_cost.py. This is only the fixed cost. It doesn’t measure whether the task succeeds or how many steps it takes.

Connection

Local, web, or both

If Zotero is running on the same computer, you don’t need any credentials. Add a key when you want writes or access from somewhere else.

read → zotero.sqlite

Local, read-only

Reads from the Zotero app on your computer. Works offline.

Zotero running with the local API enabled, and ZOTERO_LOCAL=true
read + write → local

Local, read-write

Writes go to the running Zotero app too. No sync or Storage quota involved.

Zotero 10+, and zotero-mcp authorize-local once
read local · write web

Hybrid

Reads are local and fast, and writes go through the Zotero web API. Use this on Zotero 9 and older.

ZOTERO_API_KEY and ZOTERO_LIBRARY_ID alongside local mode
read + write → web

Web API

Your synced library from anywhere, including servers and containers. WebDAV can serve attachments.

A Zotero API key and library ID
Capabilities

What it can do

The base install has no ML dependencies. Semantic search, PDF outlines, and Scite are optional extras.

Search

  • Keyword search, or conditions joined with AND/OR, including date ranges
  • Tag filters with OR and exclusions
  • Look up items by Better BibTeX citation key
  • Search your personal and group libraries at once

Semantic search

  • Find papers by meaning, with similarity scores
  • A free local embedding model, or OpenAI, Gemini, or Ollama
  • Optional passage-level chunking of full text
  • Batch embedding with the OpenAI and Gemini Batch APIs
Needs the [semantic] extra

Read

  • Metadata as Markdown, JSON, or BibTeX
  • Full text with the paper’s headings preserved
  • A PDF’s table of contents, then just the pages you need
  • Bibliographies formatted by Zotero’s own citation engine

Annotations and notes

  • Read, create, edit, and delete highlights
  • Area annotations placed on detected figures and tables
  • Sticky notes pinned to a point on the page
  • Create, update, and search notes
  • A per-paper summary of your highlights and notes

Add and organize

  • Add from a DOI, URL, ISBN, BibTeX, CSL JSON, or a local PDF or EPUB
  • Find open-access PDFs through Unpaywall, arXiv, Semantic Scholar, and PMC
  • Items already in your library are reused, not duplicated
  • Collections, bulk tag edits, and duplicate merging

Citations and discovery

  • Scite counts of supporting and contrasting citations, and retraction alerts (no account needed)
  • Find papers that cite, or are cited by, a work, via OpenAlex
  • See which items are missing a PDF
  • RSS feeds and related-item links
Optional tool groups, see Reference
Get started

Two commands to get going

Install the package, then run zotero-mcp setup. It configures Claude Desktop for you and prints the settings other clients need.

$ uv tool install "zotero-mcp-server[all]"
$ zotero-mcp setup

New to the command line? The community-built Zotero MCP Setup includes a macOS installer and one-click scripts for Mac and Windows.

Free and MIT-licensed

If Zotero MCP saves you or your lab time, sponsoring helps cover the less visible work: Windows and WSL2 edge cases, Zotero schema changes, group library support, and the search infrastructure.

The $50 and $200 tiers are meant to be expensable by labs and institutions, and include priority triage on the issues that affect your workflow.