zotero-mcp

Read-only MCP server for browsing, searching, and exporting a Zotero library from AI assistants such as Claude.

Features

• Read-only access to collections, saved searches, items, notes, attachments, tags, and citations

• Structured JSON responses (output_format="json") for AI clients that prefer machine-readable output

• Text responses by default for chat-oriented clients

• Pagination hints, filter validation, and normalized metadata fields

• Shared HTTP client with retry/backoff and clearer upstream error handling

Available tools

Requirements

• Python 3.12+

• A Zotero Web API key

• Your numeric Zotero user or group library ID

Setup

1 — Get your API credentials

1. Sign in at zotero.org and open Settings → Feeds/API.

2. Create a new private key with read-only access to your library.

3. Note the generated key and your numeric User ID or Group ID.

2 — Set environment variables

export ZOTERO_API_KEY="your_api_key_here"
export ZOTERO_LIBRARY_ID="123456"
export ZOTERO_LIBRARY_TYPE="user"   # or "group"

3 — Install dependencies

With uv:

uv sync

With pip:

python -m pip install -e .

4 — Run the server

python main.py

Or via the installed package entrypoint:

python -m zotero_mcp

Client configuration

Claude Desktop

Add the following to claude_desktop_config.json:

{
  "mcpServers": {
    "zotero": {
      "command": "python",
      "args": ["/absolute/path/to/zotero-mcp/main.py"],
      "env": {
        "ZOTERO_API_KEY": "your_api_key_here",
        "ZOTERO_LIBRARY_ID": "123456",
        "ZOTERO_LIBRARY_TYPE": "user"
      }
    }
  }
}

Restart Claude Desktop after saving.

Generic stdio MCP clients

Any stdio-based MCP client can launch the server with:

{
  "command": "python",
  "args": ["/absolute/path/to/zotero-mcp/main.py"],
  "env": {
    "ZOTERO_API_KEY": "your_api_key_here",
    "ZOTERO_LIBRARY_ID": "123456",
    "ZOTERO_LIBRARY_TYPE": "user"
  }
}

Structured output

Every tool supports:

• output_format="text" (default)

• output_format="json"

JSON mode is useful when an MCP client or agent wants explicit paging and normalized metadata:

{
  "paging": {
    "start": 0,
    "returned": 25,
    "total": 143,
    "next_start": 25,
    "has_more": true
  }
}

Common workflows

• Browse a collection: list_collection_items(collection_key="ABCD1234")

• Explore saved searches: list_saved_searches(output_format="json")

• Fetch richer child data: get_item_children(item_key="ABCD1234", item_type="note")

• Export a reference: export_item(item_key="ABCD1234", export_format="bibtex")

• Render a formatted citation: get_item_citation(item_key="ABCD1234", style="mla")

Example prompts for AI clients

• “List my saved searches as JSON.”

• “Show the latest 10 journal articles tagged ai.”

• “Export item ABCD1234 as BibTeX.”

• “Get the note content for Zotero item NOTE1234.”

• “List attachments for item ABCD1234.”

Tool reference

Common pagination and output parameters

Most list tools support:

list_items

list_collection_items / list_saved_search_items

get_item

get_item_children

search_items

get_item_citation

export_item

Known limitations

• Read-only: creating, editing, or deleting items is not supported.

• Attachment binaries: attachment file content is not downloaded.

• Saved searches: the server exposes saved searches as special collections and uses their keys for item listing.

• Single library scope: one configured user or group library per server process.

Development

Install dev dependencies

With uv:

uv sync --extra dev

With pip:

python -m pip install -e ".[dev]"

Run tests

python -m pytest tests/ -v

Build the package

python -m build

Project layout

zotero-mcp/
├── main.py               # Compatibility entry point
├── server.json           # MCP Registry metadata
├── zotero_mcp/
│   ├── __main__.py       # Packaged entry point
│   ├── client.py         # Zotero Web API v3 client
│   ├── config.py         # Constants and version metadata
│   ├── formatters.py     # Text + structured output normalization
│   └── tools.py          # MCP tool implementations
└── tests/
    ├── test_client.py
    ├── test_formatters.py
    ├── test_main.py
    ├── test_server.py
    └── test_tools.py

Changelog

0.2.0

• Added collection-scoped listing and saved-search discovery tools

• Added dedicated note, attachment, citation, and export tools

• Added structured JSON output across the tool surface

• Added stricter validation, shared HTTP client reuse, and retry/backoff logging

• Expanded automated coverage and CI expectations

0.1.0

• Initial Zotero MCP server implementation

• Six read-only tools for browsing items, collections, tags, and children

• Automatic retry on rate-limit (HTTP 429) and transient network errors

MCP Registry publishing

This repository includes a server.json file for MCP Registry publication under:

• name: io.github.nadavWeisler/zotero-mcp

• registryType: pypi

• identifier: nadavweisler-zotero-mcp

To publish a new release:

1. Publish version 0.2.0 (or newer) of nadavweisler-zotero-mcp to PyPI.

2. Install mcp-publisher.

3. Run:

   • mcp-publisher login github

   • mcp-publisher publish

v2 roadmap ideas

• Optional write operations behind explicit opt-in safeguards

• Multi-library support

• More advanced search composition for large libraries

• Client-selectable output modes tuned for specific MCP consumers