zotero-api-mcp 0.0.1

A clean, one-to-one MCP server for the Zotero API — no AI bloat, just the API

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

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

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

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.