Zotero MCP: Chat with your Research Library—Local or Web—in Claude, ChatGPT, and more.

Zotero MCP seamlessly connects your Zotero research library with ChatGPT, Claude, and other AI assistants (e.g., Cherry Studio, Chorus, Cursor) via the Model Context Protocol. Review papers, get summaries, analyze citations, extract PDF annotations, and more!

---

✨ Features

🧠 AI-Powered Semantic Search

• Vector-based similarity search over your entire research library (requires [semantic] extra)
• Multiple embedding models: Default (free, local), OpenAI, Gemini, and Ollama
• Intelligent results with similarity scores and contextual matching
• Auto-updating database with configurable sync schedules

🔍 Search Your Library

• Find papers, articles, and books by title, author, or content
• Perform complex searches with multiple criteria
• Browse collections, tags, and recent additions
• Semantic search for conceptual and topic-based discovery

📚 Access Your Content

• Retrieve detailed metadata for any item (markdown or BibTeX export)
• Get full text content (when available)
• Look up items by BetterBibTeX citation key

📝 Work with Annotations

• Extract and search PDF annotations with page numbers
• Access Zotero's native annotations
• Create and update notes and annotations
• Extract PDF table of contents / outlines (requires [pdf] extra)

✏️ Write Operations

• Add papers by DOI with auto-fetched metadata and open-access PDF cascade (Unpaywall, arXiv, Semantic Scholar, PMC)
• Add papers by URL (arXiv, DOI links, generic webpages) or from local files
• Create and manage collections, update item metadata, batch-update tags
• Find and merge duplicate items with dry-run preview
• Hybrid mode: local reads + web API writes for local-mode users

📊 Scite Citation Intelligence (optional [scite] extra)

• Citation tallies: See how many papers support, contrast, or mention each item — the MCP version of the Scite Zotero Plugin
• Retraction alerts: Scan your library for retracted or corrected papers
• No Scite account required — uses public API endpoints

🌐 Flexible Access Methods

• Local mode for offline access (no API key needed)
• Web API for cloud library access
• Hybrid mode: read from local Zotero, write via web API

⌨️ Standalone CLI (zotero-cli)

• Search, browse, and edit your library directly from the terminal — no AI assistant required
• Ideal for scripting, automation, and quick lookups
• Short aliases (s, g, ann, coll) for interactive use

🚀 Quick Install

New to the command line? Try the community-built Zotero MCP Setup — includes a macOS GUI installer (DMG), one-click install scripts for Mac/Windows, and a step-by-step guide. No Terminal experience needed.

Default Installation (core tools only)

The base install is lightweight — it includes search, metadata retrieval, annotations, and write operations. No ML/AI dependencies are pulled in.

Installing via uv (recommended)

uv tool install zotero-mcp-server
zotero-mcp setup  # Auto-configure (Claude Desktop supported)

Installing via pip

pip install zotero-mcp-server
zotero-mcp setup  # Auto-configure (Claude Desktop supported)

Installing via pipx

pipx install zotero-mcp-server
zotero-mcp setup  # Auto-configure (Claude Desktop supported)

Optional Extras

Heavy ML/PDF dependencies are separated into optional extras so the base install stays fast and small:

Extra	What it adds	Install command
semantic	Semantic search via ChromaDB, sentence-transformers, OpenAI/Gemini embeddings	pip install "zotero-mcp-server[semantic]"
pdf	PDF outline extraction (PyMuPDF) and EPUB annotation support	pip install "zotero-mcp-server[pdf]"
scite	Scite citation intelligence — tallies and retraction alerts (no account needed)	pip install "zotero-mcp-server[scite]"
all	Everything above	pip install "zotero-mcp-server[all]"

For example, with uv:

uv tool install "zotero-mcp-server[all]"    # Full install with all features
uv tool install "zotero-mcp-server[semantic]" # Just semantic search

If you only need basic library access (search, read, annotate, write), the default install with no extras is all you need.

Updating Your Installation

Keep zotero-mcp up to date with the smart update command:

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

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

🧠 Semantic Search

Zotero MCP now includes powerful AI-powered semantic search capabilities that let you find research based on concepts and meaning, not just keywords.

Setup Semantic Search

During setup or separately, configure semantic search:

# Configure 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 (text-embedding-3-small or text-embedding-3-large) - Gemini: Better quality, requires API key (gemini-embedding-001) - Ollama: Runs locally via Ollama API (requires model name, e.g., 'qwen3-embedding')

Using Ollama embeddings:

Install and start Ollama, then pull an embedding model before running zotero-mcp update-db:

ollama serve

# Small model: fast and lightweight
ollama pull nomic-embed-text

# Medium model: better multilingual retrieval quality
ollama pull bge-m3

When prompted by zotero-mcp setup --semantic-config-only, choose Ollama and use either nomic-embed-text or bge-m3 as the model name. If you change embedding models later, rebuild the index:

zotero-mcp update-db --force-rebuild

When you choose OpenAI, setup also asks whether database updates should use OpenAI Batch API. Batch updates are cheaper for large libraries, but they are asynchronous: submit the batch, wait for completion, then import the embeddings.

Update Frequency Options: - Manual: Update only when you run zotero-mcp update-db - Auto on startup: Update database every time the server starts - Daily: Update once per day automatically - Every N days: Set custom interval

Using Semantic Search

After setup, initialize your search database:

# Build the semantic search database (fast, metadata-only)
zotero-mcp update-db

# Submit OpenAI embeddings through Batch API for this update
zotero-mcp update-db --openai-batch

# Check and import completed OpenAI Batch API embeddings
zotero-mcp openai-batch-status
zotero-mcp openai-batch-import

# Force realtime OpenAI embeddings even if Batch API is enabled in config
zotero-mcp update-db --no-openai-batch

# Build with full-text extraction (slower, more comprehensive)
zotero-mcp update-db --fulltext

# Use your custom zotero.sqlite path
zotero-mcp update-db --fulltext --db-path "/Your_custom_path/zotero.sqlite"

# If you have embedding conflicts or changed models, force a rebuild
zotero-mcp update-db --force-rebuild

# Check database status
zotero-mcp db-status

Example Semantic Queries in your AI assistant: - "Find research similar to machine learning concepts in neuroscience" - "Papers that discuss climate change impacts on agriculture" - "Research related to quantum computing applications" - "Studies about social media influence on mental health" - "Find papers conceptually similar to this abstract: [paste abstract]"

The semantic search provides similarity scores and finds papers based on conceptual understanding, not just keyword matching.

🖥️ Setup & Usage

Full documentation is available at Zotero MCP docs.

Requirements - Python 3.10+ - Zotero 7+ (for local API with full-text access) - An MCP-compatible client (e.g., Claude Desktop, ChatGPT Developer Mode, Cherry Studio, Chorus)

For ChatGPT setup: see the Getting Started guide.

For Claude Desktop (example MCP client)

Configuration

After installation, either:

1. Auto-configure (recommended): bash zotero-mcp setup

2. Manual configuration: Add to your claude_desktop_config.json: json { "mcpServers": { "zotero": { "command": "zotero-mcp", "env": { "ZOTERO_LOCAL": "true", "ZOTERO_API_KEY": "YOUR_API_KEY", "ZOTERO_LIBRARY_ID": "YOUR_LIBRARY_ID" } } } }

For local read-only use, ZOTERO_LOCAL: "true" is all you need — drop the ZOTERO_API_KEY and ZOTERO_LIBRARY_ID lines entirely. Add them only to enable write mode: the local API is fast but read-only, so the server uses the Zotero web API for write operations.

• Generate an API key from https://www.zotero.org/settings/security#applications.
• ZOTERO_LIBRARY_ID is your numeric userID, shown on that same page (for a group library, use the group's ID and also set ZOTERO_LIBRARY_TYPE: "group").

Tip: if Claude Desktop reports it can't find the zotero-mcp command, use the absolute path instead (run zotero-mcp setup-info or which zotero-mcp to find it) — GUI apps don't always inherit your shell PATH.

Usage

1. Start Zotero desktop (make sure 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" - "Search my notes and annotations for mentions of 'reinforcement learning'" - "Show me papers tagged '#Arm' excluding those with '#Crypt' in my library" - "Search for papers on operating system with tag '#Arm'" - "Export the BibTeX citation for papers on machine learning" - "Find papers conceptually similar to deep learning in computer vision" (semantic search) - "Research that relates to the intersection of AI and healthcare" (semantic search) - "Papers that discuss topics similar to this abstract: [paste text]" (semantic search)

For Cherry Studio

Configuration

Go to Settings -> MCP Servers -> Edit MCP Configuration, and add the following:

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

Then click "Save".

Cherry Studio also provides a visual configuration method for general settings and tools selection.

🔧 Advanced Configuration

Using Web API Instead of Local API

For accessing your Zotero library via the web API (useful for remote setups):

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) - ZOTERO_WEBDAV_URL: Optional WebDAV folder URL for direct attachment downloads in remote mode - ZOTERO_WEBDAV_USERNAME: Optional WebDAV username - ZOTERO_WEBDAV_PASSWORD: Optional WebDAV password

Semantic Search: - ZOTERO_EMBEDDING_MODEL: Embedding model to use (default, openai, gemini, ollama) - OPENAI_API_KEY: Your OpenAI API key (for OpenAI embeddings) - OPENAI_EMBEDDING_MODEL: OpenAI model name (text-embedding-3-small, text-embedding-3-large) - OPENAI_BASE_URL: Custom OpenAI endpoint URL (optional, for use with compatible APIs) - OpenAI Batch API indexing is configured by zotero-mcp setup and can be overridden with zotero-mcp update-db --openai-batch or --no-openai-batch - GEMINI_API_KEY: Your Gemini API key (for Gemini embeddings) - GEMINI_EMBEDDING_MODEL: Gemini model name (gemini-embedding-001) - GEMINI_BASE_URL: Custom Gemini endpoint URL (optional, for use with compatible APIs) - OLLAMA_EMBEDDING_MODEL: Ollama embedding model name (qwen3-embedding by default) - OLLAMA_BASE_URL: Ollama server URL (default: http://localhost:11434) - ZOTERO_DB_PATH: Custom zotero.sqlite p