zotero-mcp

A local-only, read-only MCP server for Zotero.

AI disclosure

This tool was built by Claude and hardly verified by me. I advise against using it on your Zotero database (and if you ignore that advise, make sure you have up to date offline backups).

Features

• Local-only. Talks to the Zotero desktop client's local API on 127.0.0.1:23119. No API key, no zotero.org account, no network traffic.
• Read-only. Every tool is a retrieval call, enforced by an allowlist; the server has no code path that can add, edit, or delete anything. Note that the local API itself is not read-only — Zotero 10+ supports POST/PUT/ PATCH/DELETE on /api/ once a client obtains a local API key via POST /api/local/authorize. This server never requests such a key and holds api_key=None, so the write path stays unreachable; the read-only guarantee is enforced here, not by the API.
• stdio transport only.

Requirements

• Zotero 7 or newer, running
• Python 3.13+
• Zotero's local API enabled: Settings → Advanced → "Allow other applications on this computer to communicate with Zotero"

Without that setting the API returns 403 and every tool reports how to fix it.

Install

From a local checkout:

uv tool install .

Usage

Register it with Claude Code:

claude mcp add zotero -- uvx zotero-mcp

Or add it to your MCP client config directly:

{
  "mcpServers": {
    "zotero": {
      "command": "uvx",
      "args": [ "zotero-mcp" ]
    }
  }
}

Tools

Tool	Purpose
search_items	Search by keyword; optional item-type and tag filters. qmode="everything" searches attachment full text.
get_item	Full metadata for one item key.
get_item_children	Attachments and notes belonging to an item.
get_item_fulltext	Indexed text of an attachment (PDF, snapshot), with truncation info.
list_collections	Collections, optionally top-level only.
get_collection_items	Items inside a collection.
list_tags	Tags used in the library.
get_recent_items	Most recently added items.
library_stats	Item and collection counts.

Item keys are 8-character strings such as ABCD2345. To read a PDF's text, call get_item_children on a reference first to get its attachment key, then pass that to get_item_fulltext.

Why not read zotero.sqlite directly?

Zotero's developer documentation states that the SQLite schema is an internal implementation detail that may change between releases, and that direct access must be read-only to avoid corruption (Zotero's caching layer interferes with SQLite file locking). The local API is the supported interface, works while Zotero is running, and returns stable documented JSON.

The tradeoff: Zotero must be open. Reading the SQLite file would work with Zotero closed, at the cost of coupling to an unstable schema.

Notes

• itemType negation: the API docs document exactly three forms — itemType=book, itemType=book || journalArticle (OR), and itemType=-attachment (NOT). Negating a group is not documented, and unsupported expressions fail open: they return 200 OK with the filter silently dropped rather than a 400. Measured on this library: -attachment → 578 results, -attachment || note → 1184 (the unfiltered total), -(attachment) → 1184. An unknown type such as garbagetype returns 0 results rather than erroring. Because a broken filter yields more rows than a working one, this server sends only the documented -attachment and drops remaining notes and annotations in code, over-fetching so the requested limit is still filled.
• Results are condensed (envelope and empty fields stripped) to keep responses small; abstracts are truncated in list views but returned in full by get_item.
• ZOTERO_LIBRARY_ID and ZOTERO_LOCALE can override the defaults (0, en-US).

Tests

uv run pytest

The suite mocks pyzotero, so it runs without Zotero open.

License

Released into the public domain under the Unlicense. See LICENSE.