Zotero MCP server

The Zotero MCP Server enables your MCP clients (like Anthropic Claude App or Goose) to interact with your local Zotero library. This server provides programmatic access to search papers, manage notes, and perform other operations on your Zotero collection without leaving your preferred interface.

Installation Options

There are two ways to set up the Zotero MCP Server, depending on your preferences: using the Zotero API or directly accessing the SQLite database.

API-based Installation

1. Install the package dependencies:

pip install -e .

2. Create a .env file in the root directory with your Zotero credentials:

ZOTERO_API_KEY=your_api_key_here
ZOTERO_USER_ID=your_user_id_here

You can obtain your Zotero API key and user ID from Zotero's settings page.

SQLite-based Installation

If you prefer to bypass the Zotero API and work directly with the SQLite database:

1. Install the package dependencies:

pip install -e .

2. No API keys are required for this method.

Note: You must close Zotero completely before using the SQLite method, as SQLite locks the database when Zotero is running.

Configuring with MCP Clients

Anthropic Claude Desktop App

To integrate with the Anthropic Claude Desktop app, you need to modify its configuration file.

API Version Configuration

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "zotero-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/yourusername/path/to/zotero-mcp",
        "run",
        "python",
        "-m",
        "zotero_mcp.server"
      ]
    }
  }
}

If you encounter an error like:

{"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"claude-ai","version":"0.1.0"}},"jsonrpc":"2.0","id":0}
  error: unexpected argument '--directory' found

Use this alternative configuration instead:

{
   "mcpServers": {
      "zotero-mcp-server": {
        "command": "bash",
        "args": [
          "-c",
          "cd /Users/yourusername/path/to/zotero-mcp-server && source .venv/bin/activate && python -m zotero_mcp.server"
        ]
      }
    }
  }

Make sure to first prepare the environment with:

uv venv
source .venv/bin/activate
uv pip install ".[dev]"

SQLite Version Configuration

For the direct SQLite database access, use this configuration:

{
  "mcpServers": {
    "zotero-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/yourusername/path/to/zotero-mcp-server",
        "run",
        "python",
        "-m",
        "zotero_mcp.db_server"
      ]
    }
  }
}

Using the Server

Once configured, the Zotero MCP Server allows you to:

• Search papers by tags
• Retrieve paper details and attached notes
• Add notes to papers
• Request paper summaries

You can interact with your Zotero library directly through supported MCP clients like the Anthropic Claude App. The server handles the communication between your client and Zotero, providing a seamless experience for managing your research papers and notes.

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-mcp-server" '{"command":"bash","args":["-c","cd /Users/shahswai/personal/zotero-mcp-server && source .venv/bin/activate && python -m zotero_mcp.server"]}'

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-mcp-server": {
            "command": "bash",
            "args": [
                "-c",
                "cd /Users/shahswai/personal/zotero-mcp-server && source .venv/bin/activate && python -m zotero_mcp.server"
            ]
        }
    }
}

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-mcp-server": {
            "command": "bash",
            "args": [
                "-c",
                "cd /Users/shahswai/personal/zotero-mcp-server && source .venv/bin/activate && python -m zotero_mcp.server"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect