zotero-api-mcp

A clean, one-to-one MCP server for the Zotero API, just the API.

Features

• 22 MCP tools covering the full Zotero API surface

• Local API support (ZOTERO_LOCAL=true) — no API key needed

• Web API support with interactive setup wizard

• Full CRUD: create items by DOI, arXiv, ISBN; update metadata; delete to trash

• Collections: create, add/remove items, search

• Notes & Annotations: read, create

• Attachments: add files or URLs, read metadata

• Library management: stats, trash, groups, tags

• Secure by default: API key stored with SecretStr, XML parsing via defusedxml

• Configuration: .env file support with ZOTERO_ prefix, pydantic-settings

• Multi-library support: Query any group or user library per-call without reconfiguring

Related MCP server: zotero-mcp

Multi-Library Support

All tools accept optional library_id and library_type keyword parameters to override the default library configured in your environment. This lets you query multiple Zotero group libraries without restarting the server or changing your .env file.

Example: Query a group library from any tool:

zotero_search_items(query="machine learning", library_id="<group-id>", library_type="group")
zotero_get_item("ABC12345", library_id="<group-id>", library_type="group")
zotero_get_collection_items("XYZ99999", library_id="<group-id>", library_type="group")

• library_id — The Zotero library ID (user ID or group ID)

• library_type — Either "user" or "group"

• Both default to your configured ZOTERO_LIBRARY_ID / ZOTERO_LIBRARY_TYPE when omitted

• Works with all 22 tools — search, items, collections, notes, annotations, and attachments

• Stateless: each call is independent, no session-level switching needed

Quick Start

# Run directly (auto-installs)
uvx zotero-api-mcp serve

# Or install globally
uv tool install zotero-api-mcp
zotero-api-mcp serve

Local Mode (no API key)

Set the environment variable and run:

ZOTERO_LOCAL=true uvx zotero-api-mcp serve

Requires Zotero running with "Allow other applications to access Zotero" enabled in Preferences → Advanced → General.

Web API Mode

zotero-api-mcp setup

You'll need a Zotero API key from https://www.zotero.org/settings/keys and your library ID.

MCP Configuration

VS Code / Cline / Claude Desktop

Local mode (read-only, no API key):

{
  "servers": {
    "zotero-api": {
      "type": "stdio",
      "command": "uvx",
      "args": ["zotero-api-mcp", "serve"],
      "env": {
        "ZOTERO_LOCAL": "true"
      }
    }
  }
}

Web API mode (full read/write, requires API key):

{
  "servers": {
    "zotero-api": {
      "type": "stdio",
      "command": "uvx",
      "args": ["zotero-api-mcp", "serve"],
      "env": {
        "ZOTERO_API_KEY": "<your-api-key>",
        "ZOTERO_LIBRARY_ID": "<your-user-id>",
        "ZOTERO_LIBRARY_TYPE": "user"
      }
    }
  }
}

Get your API key at https://www.zotero.org/settings/keys and find your user ID there too. Set ZOTERO_LIBRARY_TYPE to "group" if your default library is a group.

Tools

Search & Discovery (9 tools)

• zotero_search_items — Search by query, type, tag, or collection

• zotero_get_item — Full details for a specific item

• zotero_get_item_children — Notes and attachments for an item

• zotero_search_collections — List/search collections

• zotero_get_collection_items — Items in a collection

• zotero_search_tags — List/search tags

• zotero_get_trash — Items in trash

• zotero_get_library_stats — Library statistics

• zotero_get_groups — Group libraries

Item Management (5 tools)

• zotero_add_by_doi — Add paper by DOI (CrossRef metadata)

• zotero_add_by_arxiv — Add paper by arXiv ID

• zotero_add_by_isbn — Add book by ISBN (OpenLibrary metadata)

• zotero_update_item — Update title, abstract, date, extra

• zotero_delete_items — Move items to trash

Collections (3 tools)

• zotero_create_collection — Create a new collection

• zotero_add_to_collection — Add items to a collection

• zotero_remove_from_collection — Remove items from a collection

Notes (2 tools)

• zotero_add_note — Add a note to an item

• zotero_read_note — Read a note's content

Annotations (1 tool)

• zotero_read_annotations — Read PDF annotations for an item

Attachments (2 tools)

• zotero_add_attachment — Attach a file or URL to an item

• zotero_read_attachment — Get attachment metadata

Comparison with other Zotero MCP servers

Development

See CONTRIBUTING.md for full setup and guidelines.

# Install dependencies (requires uv)
uv sync --group dev

# Run tests
just test         # Quick: current Python
just test-all     # Full: Python 3.12–3.14 via tox

# Version management
just version      # Show current version
just bump-patch   # 0.0.1 → 0.0.2, creates git tag + commit

License

MIT — see LICENSE for details.