📌Overview

Purpose: The Model Context Protocol (MCP) server enables access to Zotero libraries through AI assistants, facilitating efficient interactions with Zotero data.

Overview: This Python-based server implements the MCP specifically for Zotero, allowing users to leverage their Zotero libraries for enhanced AI-assisted functionality. It supports multiple interaction types with Zotero items, making it a useful tool for integrating citation management within AI environments.

Key Features:

zotero_search_items: Enables users to search for specific items in their Zotero library using text queries, streamlining the item retrieval process.
zotero_item_metadata: Provides detailed metadata about selected Zotero items, ensuring that users can access essential bibliographic information easily.
zotero_item_fulltext: Allows retrieval of the complete text for specific Zotero items (e.g., PDFs), enhancing research and reference capabilities within AI applications.

Model Context Protocol server for Zotero

This project is a Python server implementing the Model Context Protocol (MCP) for Zotero, providing access to your Zotero library within AI assistants. It implements a useful set of interactions with Zotero for use with MCP clients.

Features

The MCP server provides the following tools:

zotero_search_items: Search for items in your Zotero library using a text query
zotero_item_metadata: Get detailed metadata information about a specific Zotero item
zotero_item_fulltext: Get the full text of a specific Zotero item (e.g., PDF contents)

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

Each tool returns formatted text with relevant information from your Zotero items, which AI assistants such as Claude can use sequentially.

Installation

This server can run against either a local API offered by the Zotero desktop application or the Zotero Web API.

Using the Local Zotero API

The local API requires the Zotero app running on the same computer with the API enabled. To enable the local API:

Open Zotero and go to "Zotero Settings"
Under the "Advanced" tab, check "Allow other applications on this computer to communicate with Zotero".

Note:
For access to the /fulltext endpoint on the local API (to retrieve full content of items), you'll need to install a Zotero Beta Build (as of 2025-03-30). This requirement will be removed once Zotero 7.1 is released. Alternatively, you can use the Web API.

Using the Zotero Web API

To use the Web API, create an API key and find your Library ID in your Zotero account settings: https://www.zotero.org/settings/keys

Configuration Options

ZOTERO_LOCAL=true: Use the local Zotero API (default: false)
ZOTERO_API_KEY: Your Zotero API key (not required for local API)
ZOTERO_LIBRARY_ID: Your Zotero library ID (not required for local API)
ZOTERO_LIBRARY_TYPE: Type of library (user or group, default: user)

Using `uvx` with Local Zotero API

Add the following to the mcpServers configuration for Claude Desktop or direct Python install with uvx:

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

The --update flag pulls the latest version when available.

Using Docker with Zotero Web API

Run the MCP server in a Docker container by using this configuration, replacing placeholders with your 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

It's possible to use Docker to connect to the local Zotero API, but you must ensure network access to the Zotero app’s local API interface.

Development

To contribute or make changes:

Clone this repository
Install dependencies with uv by running: uv sync
Create a .env file with the environment variables above

Start the MCP Inspector for local development:

npx @modelcontextprotocol/inspector uv run zotero-mcp

To test with Claude Desktop, get the path by running:

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

Add this path to your Claude Desktop configuration:

{
  "mcpServers": {
    "zotero": {
      "command": "/path/to/zotero-mcp/.venv/bin/zotero-mcp",
      "env": {
        // Your configuration here
      }
    }
  }
}

Running Tests

Run the test suite with:

uv run pytest

Docker Development

Build the Docker image:

docker build . -t zotero-mcp:local

Test with MCP Inspector passing environment variables:

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

zotero-mcp