Installation Guide | Zotero MCP

Prerequisites

Required Software

Python 3.10+ - Required for running Zotero MCP
Zotero 7+ - For local API with full-text access
MCP-compatible AI client - Claude Desktop, ChatGPT, Cherry Studio, Cursor, or Chorus

Enable Local API in Zotero

For the best experience, enable the local Zotero API:

Open Zotero
Go to Edit > Preferences > Advanced
Toggle on "Allow other applications on this computer to communicate with Zotero"
Click OK to save

Tip: Local API provides full-text access and is recommended for most users. Web API is useful for remote access but has limited attachment support.

UV Installation Recommended

UV is the fastest Python package manager. It provides quick installation and isolated environments.

Step 1: Install UV (if not installed)

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Step 2: Install Zotero MCP

uv tool install "git+https://github.com/54yyyu/zotero-mcp.git"

Step 3: Auto-configure for Claude Desktop

zotero-mcp setup

Done! Restart Claude Desktop and you're ready to go.

Pip Installation

Classic Python installation using pip:

Install from GitHub

pip install git+https://github.com/54yyyu/zotero-mcp.git

Auto-configure

zotero-mcp setup

If you're using a virtual environment or conda, make sure it's activated before installing.

Smithery Installation

Smithery is a package manager for AI tools. It automatically handles configuration.

Requirements

Node.js installed on your system

Installation

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

Smithery will automatically:

Install the latest version of Zotero MCP
Configure it for Claude Desktop
Set up all necessary paths

Semantic Search Setup New Feature

Enable AI-powered semantic search to find papers by meaning, not just keywords.

Step 1: Configure Semantic Search

# During initial setup (recommended)
zotero-mcp setup

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

Step 2: Choose Embedding Model

During setup, you'll be prompted to select an embedding model:

Model	Cost	Quality	Requirements
Default (all-MiniLM-L6-v2)	Free	Good	Runs locally, no API key
HuggingFace	Free	Good	Runs locally, no API key
OpenAI	Paid	Better	OPENAI_API_KEY required
Gemini	Paid	Better	GEMINI_API_KEY required

Step 3: Build Search Database

# Quick build (metadata only)
zotero-mcp update-db

# Full build with text content (better search results)
zotero-mcp update-db --fulltext

# Custom Zotero database path
zotero-mcp update-db --fulltext --db-path "/path/to/zotero.sqlite"

Update Frequency

Configure how often the database syncs:

Manual - Only when you run zotero-mcp update-db
Auto on startup - Every time the server starts
Daily - Once per day automatically
Every N days - Custom interval

Client Configuration

Claude Desktop

Auto-configure (recommended):

zotero-mcp setup

Manual configuration:

Add to your claude_desktop_config.json:

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

Config file locations:

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

Cherry Studio

Go to Settings → MCP Servers → Edit MCP Configuration:

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

Other MCP Clients (Cursor, Chorus)

Most MCP clients use a similar configuration format. The key settings are:

Command: zotero-mcp
Environment: ZOTERO_LOCAL=true for local API
Transport: stdio (default) or streamable-http

For streamable HTTP transport:

zotero-mcp serve --transport streamable-http

ChatGPT Setup New

Zotero MCP now supports ChatGPT! The setup requires a few additional steps.

Step 1: Install with no-claude flag

pip install git+https://github.com/54yyyu/zotero-mcp.git
zotero-mcp setup --no-claude

Step 2: Configure for OpenAI

The setup will create a standalone configuration optimized for ChatGPT.

ChatGPT requires specific tool names (search and fetch). The no-claude configuration ensures compatibility.

For detailed ChatGPT configuration, see the Getting Started guide.

Web API Setup

Use the Zotero Web API for remote access to your library.

Step 1: Get API Credentials

Go to zotero.org/settings/keys
Create a new API key with the appropriate permissions
Note your Library ID (shown on the same page)

Step 2: Configure

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

Environment Variables

ZOTERO_LOCAL=false
ZOTERO_API_KEY=your_api_key
ZOTERO_LIBRARY_ID=your_library_id
ZOTERO_LIBRARY_TYPE=user  # or 'group' for group libraries

Note: Web API has limited attachment access. Some features like full-text extraction may not work as well as with the local API.

Updating Zotero MCP

Keep Zotero MCP up to date with the smart update command:

# Check for updates without installing
zotero-mcp update --check-only

# Update to latest version (preserves configurations)
zotero-mcp update

# Force update even if up to date
zotero-mcp update --force

The update command will:

Detect your installation method (uv, pip, conda, pipx)
Preserve all your configurations
Update to the latest version

Configuration backups are stored in ~/.config/zotero-mcp/

Verification

Check Installation

# Check version
zotero-mcp version

# Show installation and config info
zotero-mcp setup-info

# Check semantic search database status
zotero-mcp db-status

Test with Your AI Client

Make sure Zotero is running
Restart your AI client (Claude Desktop, etc.)
Try a simple query: "Search my Zotero library for recent papers"

Success! If you see search results, everything is working correctly.

Troubleshooting

If you encounter issues:

Ensure Zotero is running with local API enabled
Restart your AI client after configuration changes
Check the FAQ section for common issues
Run zotero-mcp setup-info to verify your configuration