Zotero MCP v0.13.1
0.13.1Sticky notes, and related papers that add up

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
Set up a client Browse the tools
Python 3.10+Zotero 7+MIT licensed
Recent releases

What’s new

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

Two ways in

An MCP server, or a skill for agents with a shell

Both use the same config. Use the MCP server when your client supports MCP but has no shell. Use the skill when your agent can run commands.

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

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 tools50 tools, every request17,414
  • MCP, default tools38 tools, every request13,448
  • Skill, instructions loadedonly when it’s used1,368
  • 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.

Read the setup guide Join the Discord

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.

GitHub Sponsors Buy Me a Coffee