Zotero MCP server for AI agents

This MCP server provides access to your Zotero library within AI assistants through the Model Context Protocol (MCP). It allows AI assistants to search your Zotero library, retrieve metadata, and access the full text of your documents.

Features

This MCP server offers three primary tools:

zotero_search_items: Search your Zotero library using text queries
zotero_item_metadata: Retrieve detailed metadata about specific Zotero items
zotero_item_fulltext: Access the full text content of Zotero items (PDF contents)

These tools return formatted text that AI assistants can use sequentially - first searching for items, then retrieving their metadata or content.

Installation Options

Setup for Local Zotero API

The server can connect to your local Zotero desktop application:

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

For access to the /fulltext endpoint on the local API, you currently need a Zotero Beta Build (as of 2025-03-30). This requirement will be removed when version 7.1 is released.

Setup for Zotero Web API

Alternatively, you can use the Zotero Web API:

Create an API key at https://www.zotero.org/settings/keys
Note your Library ID (usually your User ID) from the same page

Configuration Options

The server uses these environment variables:

ZOTERO_LOCAL: Set to "true" to use the local Zotero API (default: false)
ZOTERO_API_KEY: Your Zotero API key (not needed for local API)
ZOTERO_LIBRARY_ID: Your Zotero library ID (not needed for local API)
ZOTERO_LIBRARY_TYPE: Library type (user or group, default: user)

Installation Methods

Using `uvx` with Local Zotero API

To use with Claude Desktop via uvx:

Add this to your Claude Desktop configuration:

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

The --upgrade flag is optional and will pull the latest version when available.

Using Docker with Zotero Web API

To run the server in a Docker container:

Add this to your MCP client configuration (replacing placeholders with your values):

{
  "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 Docker image, run:

docker pull ghcr.io/kujenga/zotero-mcp:main

Using the MCP Server

Once configured, the Zotero MCP server becomes available to compatible MCP clients like Claude. You can:

Search your Zotero library: Ask the AI to find articles or documents related to specific topics
Get metadata: Request information about documents (authors, publication dates, etc.)
Analyze document contents: Ask the AI to read and summarize the full text of your documents

Example queries:

"Find papers about machine learning in my Zotero library"
"Get the abstract of the paper about quantum computing I saved recently"
"Summarize the key points from my saved article on climate change"

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "zotero" '{"command":"uvx","args":["--upgrade","zotero-mcp"],"env":{"ZOTERO_LOCAL":"true","ZOTERO_API_KEY":"","ZOTERO_LIBRARY_ID":""}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect

Zotero MCP server