playbooks
Learn Cursor Rules Windsurf Rules MCPs Modes
Log in

Zotero MCP server

Enables direct interaction with Zotero reference management libraries for searching literature, retrieving metadata and full-text content, managing collections, and organizing research materials.
Back to servers
Setup instructions
Provider
gh-54yyyu
Release date
Mar 23, 2025
Language
Python
Stats
242 stars
View on GitHub

Zotero MCP connects your Zotero research library with Claude and other AI assistants through the Model Context Protocol. This powerful tool enables you to discuss papers, get summaries, analyze citations, extract PDF annotations, and perform semantic searches across your research materials.

Installation Options

Installing via Smithery

To automatically install Zotero MCP for Claude Desktop using Smithery:

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

Manual Installation

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

Keeping Updated

To check for updates:

zotero-mcp update --check-only

To update to the latest version (preserves all configurations):

zotero-mcp update

Setting Up Semantic Search

Configure semantic search during initial setup or separately:

# During initial setup (recommended)
zotero-mcp setup

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

Available Embedding Models

  • Default (all-MiniLM-L6-v2): Free, runs locally, good for most use cases
  • OpenAI: Better quality, requires API key
  • Gemini: Better quality, requires API key

Initialize Your Search Database

After setup, build your semantic search database:

# Build the semantic search database
zotero-mcp update-db

# Check database status
zotero-mcp db-status

Using Zotero MCP

Requirements

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

Setting Up for Claude Desktop

Automatic Configuration (Recommended)

zotero-mcp setup

Manual Configuration

Add to your claude_desktop_config.json:

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

Using Zotero MCP with Claude

  1. Start Zotero desktop (ensure local API is enabled in preferences)
  2. Launch Claude Desktop
  3. Access the Zotero-MCP tool through Claude Desktop'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)
  • "Research that relates to the intersection of AI and healthcare" (semantic search)

Setting Up for 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"
      }
    }
  }
}

Then click "Save".

Advanced Configuration

Using Web API Instead of Local API

For accessing your Zotero library via the web API:

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

Environment Variables

Zotero Connection:

  • ZOTERO_LOCAL=true: Use the 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_LIBRARY_TYPE: The type of library (user or group, default: user)

Semantic Search:

  • ZOTERO_EMBEDDING_MODEL: Embedding model to use (default, openai, gemini)
  • OPENAI_API_KEY: Your OpenAI API key (for OpenAI embeddings)
  • OPENAI_EMBEDDING_MODEL: OpenAI model name
  • GEMINI_API_KEY: Your Gemini API key (for Gemini embeddings)
  • GEMINI_EMBEDDING_MODEL: Gemini model name

Useful Command-Line Options

# Run the server directly
zotero-mcp serve

# Setup and configuration
zotero-mcp setup --help                    # Get help on setup options
zotero-mcp setup-info                      # Show installation path and config info

# Updates and maintenance
zotero-mcp update                          # Update to latest version
zotero-mcp update --check-only             # Check for updates without installing

# Semantic search database management
zotero-mcp update-db                       # Update semantic search database
zotero-mcp update-db --force-rebuild       # Force complete database rebuild
zotero-mcp db-status                       # Show database status and info

# General
zotero-mcp version                         # Show current version

Available Tools

Semantic Search Tools

  • zotero_semantic_search: AI-powered similarity search with embedding models
  • zotero_update_search_database: Manually update the semantic search database
  • zotero_get_search_database_status: Check database status and configuration

Search Tools

  • zotero_search_items: Search your library by keywords
  • zotero_advanced_search: Perform complex searches with multiple criteria
  • zotero_get_collections: List collections
  • zotero_get_collection_items: Get items in a collection
  • zotero_get_tags: List all tags
  • zotero_get_recent: Get recently added items
  • zotero_search_by_tag: Search your library using custom tag filters

Content Tools

  • zotero_get_item_metadata: Get detailed metadata (supports BibTeX export)
  • zotero_get_item_fulltext: Get full text content
  • zotero_get_item_children: Get attachments and notes

Annotation & Notes Tools

  • zotero_get_annotations: Get annotations (including direct PDF extraction)
  • zotero_get_notes: Retrieve notes from your Zotero library
  • zotero_search_notes: Search in notes and annotations
  • zotero_create_note: Create a new note for an item (beta feature)

Troubleshooting

General Issues

  • No results found: Ensure Zotero is running and the local API is enabled
  • Can't connect to library: Check your API key and library ID if using web API
  • Full text not available: Make sure you're using Zotero 7+ for local full-text access

Semantic Search Issues

  • "Missing required environment variables": Run zotero-mcp setup to configure your environment
  • Database update takes long: This is normal for large libraries. Use --limit parameter for testing
  • Semantic search returns no results: Ensure the database is initialized with zotero-mcp update-db

Update Issues

  • Update command fails: Check your internet connection and try zotero-mcp update --force
  • Configuration lost after update: Check ~/.config/zotero-mcp/ for backup files

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

Want to 10x your AI skills?

Get a free account and learn to code + market your apps using AI (with or without vibes!).

Nah, maybe later