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

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

Feature	zotero-api-mcp	zotero-mcp (kujenga)	zotero-mcp-lite (xmruuu)	zotero-mcp-server (54yyyu)
Tools	22	3	9	~30
Philosophy	1:1 API mapping	Minimal	Read-focused	AI-heavy
CRUD (create/update/delete)	✅	❌	❌	✅
DOI/arXiv/ISBN import	✅	❌	❌	✅
Collection management	✅	❌	❌	✅
Attachment management	✅	❌	❌	❌
Local API (no key)	✅	❌	✅	❌
Semantic search / AI	❌	❌	❌	✅
Dependencies	6	4	9	97

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.