Zotero Model Context Protocol Server

To run the server using the local Zotero API with Claude Desktop, add the following configuration to your mcpServers settings. This method uses uvx to run the package directly.

{
  "mcpServers": {
    "zotero": {
      "command": "uvx",
      "args": ["zotero-mcp@latest"],
      "env": {
        "ZOTERO_LOCAL": "true",
        "ZOTERO_API_KEY": "",
        "ZOTERO_LIBRARY_ID": ""
      }
    }
  }
}

To run the server in a Docker container using the Zotero Web API, add the following to your mcpServers configuration. Replace PLACEHOLDER with your actual Zotero API key and Library ID.

{
  "mcpServers": {
    "zotero": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "ZOTERO_API_KEY=PLACEHOLDER",
        "-e", "ZOTERO_LIBRARY_ID=PLACEHOLDER",
        "ghcr.io/kujenga/zotero-mcp:main"
      ]
    }
  }
}

To update the image, run: docker pull ghcr.io/kujenga/zotero-mcp:main

To use the server with the local Zotero desktop application (which is often more responsive), you must enable the local API in Zotero:

1. Open the Zotero desktop application.
2. Open Zotero Settings.
3. Navigate to the Advanced tab.
4. Check the box: "Allow other applications on this computer to communicate with Zotero".

Note: The local API indexes citation keys for quick searches, whereas the Web API does not.

To contribute to or develop the Zotero MCP server:

1. Clone the repository.
2. Install dependencies using uv:

   uv sync

3. Create a .env file in the project root and populate it with the required environment variables (ZOTERO_LOCAL, ZOTERO_API_KEY, etc.).

Debugging with MCP Inspector

To test the server locally using the MCP Inspector, run:

npx @modelcontextprotocol/inspector uv run zotero-mcp

Testing against Claude Desktop

1. Find the path to your local virtual environment binary:

   echo $PWD/.venv/bin/zotero-mcp

2. Add that path to your Claude Desktop configuration:
```json
{
  "mcpServers": {
    "zotero": {
      "command": "/path/to/zotero-mcp/.venv/bin/zotero-mcp",
      "env": {
        "ZOTERO_LOCAL": "true"
      }
    }
  }
}

The server uses the following environment variables for configuration:

The Zotero MCP server provides three primary tools for interacting with your Zotero library through an AI assistant:

• zotero_search_items: Search for items in your Zotero library using a text query.
• zotero_item_metadata: Retrieves complete metadata for a specific item, including publication details, identifiers, timestamps, and library information.
• zotero_item_fulltext: Retrieves the full text content of a specific item (e.g., the contents of a PDF).

AI assistants can use these tools sequentially, for example, by searching for an item first and then retrieving its metadata or full text.

To execute the test suite for the Zotero MCP server, use uv run pytest:

uv run pytest

Use get_zotero_client() to obtain an authenticated pyzotero.Zotero instance. The function automatically reads configuration from environment variables. It supports both the remote Zotero Web API and a local Zotero instance.

Required Environment Variables

• ZOTERO_LIBRARY_ID: Your Zotero library ID.
• ZOTERO_API_KEY: Your Zotero API key (required for Web API).

Optional Environment Variables

• ZOTERO_LIBRARY_TYPE: The type of library (e.g., user or group). Defaults to user.
• ZOTERO_LOCAL: Set to true, yes, or 1 to use the local Zotero API. When true, ZOTERO_LIBRARY_ID defaults to "0" if not provided.

from zotero_mcp.client import get_zotero_client

# This will use environment variables like ZOTERO_LIBRARY_ID and ZOTERO_API_KEY
zot = get_zotero_client()

The CLI accepts the following transport configuration:

--transport
    choices=["stdio", "sse"]
    default="stdio"
    help="Transport to use"

The Zotero Model Context Protocol (MCP) server can be started using the command line. You can specify the communication transport method using the --transport flag. By default, the server uses stdio transport, which is standard for local MCP integrations (e.g., with Claude Desktop). Alternatively, you can use sse (Server-Sent Events) for web-based transport.

# Start with default stdio transport
python -m zotero_mcp.cli

# Start with SSE transport
python -m zotero_mcp.cli --transport sse

The AttachmentDetails class is a Pydantic model used to represent the metadata of a Zotero attachment.

from zotero_mcp.client import AttachmentDetails

# Example of the structure returned by get_attachment_details
details = AttachmentDetails(key="XYZ789", content_type="application/pdf")