Zotero MCP

🚀 Zotero's Model Context Protocol (MCP) Server

This project is a Python-based server that integrates Model Context Protocol (MCP) with Zotero, enabling you to access your Zotero library through AI assistants. The project aims to implement a small but practical set of interactive operations for communication with MCP clients.

✨ Features

This MCP server provides the following tools:

• zotero_search_items: Search for items in your Zotero library using a text query.
• zotero_item_metadata: Retrieve detailed metadata information for a specific Zotero item.
• zotero_item_fulltext: Obtain the full-text content (e.g., PDF file) of a specific Zotero item.

These tools can be discovered and accessed via any MCP client or through the MCP Inspector.

Each tool returns formatted text containing relevant Zotero item information. AI assistants (such as Claude) can use them sequentially, first searching for items and then retrieving their metadata or full-text content.

📦 Installation

This server can communicate with Zotero's local API or remote Web API. Here are two installation methods:

Method 1: Using Docker Container

Add the following configuration to the mcp.json file, replacing the placeholders with your actual API key and library ID:

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

Method 2: Local Installation

1. Clone this repository.
2. Install dependencies using uv by running the command:

   uv sync
   

3. Create a .env file in the project root directory, containing the following environment variables:

# When using the local API
ZOTERO_API=local

# Or when using the remote Web API
ZOTERO_API_KEY=your_api_key_here
ZOTERO_LIBRARY_ID=your_library_id_here

🔧 Technical Details

Development Information

To develop or contribute to the code, follow these steps:

1. Clone this repository.
2. Install dependencies using uv by running the command:

   uv sync
   

3. Create a .env file in the project root directory, containing the required environment variables.

Start the MCP Inspector for local development:

npx @modelcontextprotocol/inspector uv run zotero-mcp

To test the integration with Claude Desktop, add the following to your Claude configuration, replacing /path/to with the actual path:

{
  "mcpServers": {
    "zotero": {
      "command": "/path/to/zotero-mcp/.venv/bin/zotero-mcp",
      "env": {
        // Add the required environment variable configuration
      }
    }
  }
}

Running Tests

To run the test suite, run the command:

uv run pytest

Docker Development

Build the container image using the following command:

docker build . -t zotero-mcp:local

To test the container via the Inspector, run the command:

npx @modelcontextprotocol/inspector \
    -e ZOTERO_API_KEY=$ZOTERO_API_KEY \
    -e ZOTERO_LIBRARY_ID=$ZOTERO_LIBRARY_ID \
    docker run --rm -i \
        --env ZOTERO_API_KEY \
        --env ZOTERO_LIBRARY_ID \
        zotero-mcp:local

📚 Documentation

• https://modelcontextprotocol.io/tutorials/building-mcp-with-llms
• https://github.com/modelcontextprotocol/python-sdk
• https://pyzotero.readthedocs.io/en/latest/
• https://www.zotero.org/support/dev/web_api/v3/start