Zotero MCP server for AI agents

Zotero MCP provides a seamless integration between your Zotero research library and AI assistants like Claude through the Model Context Protocol. This tool enables you to search your library, access content, work with annotations, and even perform AI-powered semantic searches based on concepts rather than just keywords.

Installation Options

Standard Installation

You can install Zotero MCP using either uv or pip:

Using uv

uv tool install "git+https://github.com/54yyyu/zotero-mcp.git"
zotero-mcp setup  # Auto-configure for Claude Desktop

Using pip

pip install git+https://github.com/54yyyu/zotero-mcp.git
zotero-mcp setup  # Auto-configure for Claude Desktop

Using Smithery

For automatic installation with Claude Desktop via Smithery:

npx -y @smithery/cli install @54yyyu/zotero-mcp --client claude

Keeping Up to Date

Stay current with the latest features using the update command:

# Check for available updates
zotero-mcp update --check-only

# Apply the latest update (preserves your configurations)
zotero-mcp update

Setting Up Semantic Search

Zotero MCP includes AI-powered semantic search that finds research based on concepts and meaning.

Configuration

Configure semantic search during initial setup or separately:

# During initial setup (recommended)
zotero-mcp setup

# Or configure only semantic search
zotero-mcp setup --semantic-config-only

Embedding Model Options

Default (all-MiniLM-L6-v2): Free local model, suitable for most users
OpenAI: Better quality, requires API key
Gemini: Better quality, requires API key

Building Your Search Database

After setup, initialize your semantic search database:

# Basic database build (metadata-only, faster)
zotero-mcp update-db

# Comprehensive database with full-text extraction
zotero-mcp update-db --fulltext

# Check your database status
zotero-mcp db-status

Client Setup

Claude Desktop Configuration

After installation, you can configure Claude Desktop in two ways:

1. Automatic Configuration (Recommended)

zotero-mcp setup

2. Manual Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "zotero": {
      "command": "zotero-mcp",
      "env": {
        "ZOTERO_LOCAL": "true"
      }
    }
  }
}

Cherry Studio Configuration

In Cherry Studio, go to Settings → MCP Servers → Edit MCP Configuration, and add:

{
  "mcpServers": {
    "zotero": {
      "name": "zotero",
      "type": "stdio",
      "isActive": true,
      "command": "zotero-mcp",
      "args": [],
      "env": {
        "ZOTERO_LOCAL": "true"
      }
    }
  }
}

Using Zotero MCP

Requirements

Python 3.10+
Zotero 7+ (for local API with full-text access)
Claude Desktop or compatible AI assistant

Basic Usage

Start Zotero desktop (ensure local API is enabled in preferences)
Launch Claude Desktop
Access Zotero-MCP through Claude's tools interface

Example Prompts

"Search my library for papers on machine learning"
"Find recent articles I've added about climate change"
"Summarize the key findings from my paper on quantum computing"
"Extract all PDF annotations from my paper on neural networks"
"Find papers conceptually similar to deep learning in computer vision" (semantic search)
"Export the BibTeX citation for papers on machine learning"

Advanced Configuration

Using Web API Instead of Local API

For remote access to your Zotero library:

zotero-mcp setup --no-local --api-key YOUR_API_KEY --library-id YOUR_LIBRARY_ID

Key Environment Variables

ZOTERO_LOCAL=true: Use local Zotero API (default: false)
ZOTERO_API_KEY: Your Zotero API key (for web API)
ZOTERO_LIBRARY_ID: Your Zotero library ID (for web API)
ZOTERO_EMBEDDING_MODEL: Embedding model for semantic search

Useful Command-Line Options

# Run the server directly
zotero-mcp serve

# View setup options
zotero-mcp setup --help

# Display installation path and configuration info
zotero-mcp setup-info

# Force rebuild semantic search database with full-text
zotero-mcp update-db --fulltext --force-rebuild

PDF Annotation Extraction

Zotero MCP supports advanced PDF annotation extraction:

Extracts annotations directly from PDF files
Supports searching through PDF annotations and comments
Includes image annotation support
Works alongside Zotero's native annotation system

For optimal annotation extraction, installing the Better BibTeX plugin for Zotero is highly recommended.

Troubleshooting

Common Issues

No results found: Ensure Zotero is running with local API enabled in preferences
Can't connect to library: Verify API key and library ID if using web API
Full text unavailable: Confirm you're using Zotero 7+ for local full-text access
Semantic search returns no results: Initialize database with zotero-mcp update-db
Limited search quality: Use zotero-mcp update-db --fulltext for better results
Update command fails: Check internet connection, try zotero-mcp update --force

For better semantic search results, using full-text indexing is recommended: zotero-mcp update-db --fulltext

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":"zotero-mcp","env":{"ZOTERO_LOCAL":"true"}}'

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": "zotero-mcp",
            "env": {
                "ZOTERO_LOCAL": "true"
            }
        }
    }
}

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": "zotero-mcp",
            "env": {
                "ZOTERO_LOCAL": "true"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect