<!-- mcp-name: io.github.54yyyu/zotero-mcp -->

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

<p align="center"> <a href="https://www.zotero.org/"> <img src="https://img.shields.io/badge/Zotero-CC2936?style=for-the-badge&logo=zotero&logoColor=white" alt="Zotero"> </a> <a href="https://www.anthropic.com/claude"> <img src="https://img.shields.io/badge/Claude-6849C3?style=for-the-badge&logo=anthropic&logoColor=white" alt="Claude"> </a> <a href="https://chatgpt.com/"> <img src="https://img.shields.io/badge/ChatGPT-74AA9C?style=for-the-badge&logo=openai&logoColor=white" alt="ChatGPT"> </a> <a href="https://modelcontextprotocol.io/introduction"> <img src="https://img.shields.io/badge/MCP-0175C2?style=for-the-badge&logoColor=white" alt="MCP"> </a> <a href="https://pypi.org/project/zotero-mcp-server/"> <img src="https://img.shields.io/pypi/v/zotero-mcp-server?style=for-the-badge&logo=pypi&logoColor=white" alt="PyPI"> </a> <a href="https://discord.gg/BvgjbcBUqg"> <img src="https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"> </a> </p>

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

Two semantic_search.embedding_config keys tune the Ollama path for slower hardware or very large libraries:

"embedding_config": {
  "model_name": "bge-m3",
  "timeout": 600,            // HTTP timeout per /api/embed call (default 120s)
  "request_batch_size": 64   // documents per request (default 64)
}

Raise timeout if indexing reports Read timed out; lower request_batch_size to make each request cover less GPU work, which usually fixes timeouts more reliably than raising the timeout alone.

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.

Text Extraction Settings

PDFs are parsed with pdf-inspector, which produces Markdown with the document's heading structure intact. These keys live under semantic_search.extraction in ~/.config/zotero-mcp/config.json:

{
  "semantic_search": {
    "extraction": {
      "pdf_max_pages": 50,
      "fulltext_display_max_pages": 10,
      "attachment_priority": ["markdown", "pdf", "html", "other"]
    }
  }
}

| Key | Default | What it does | |---|---|---| | pdf_max_pages | 50 | Pages extracted per PDF when indexing. Raising it does not widen what search sees on its own — that is bounded by the embedding model's token limit or chunking.max_chunks_per_item. | | fulltext_display_max_pages | 10 | Pages returned by zotero_get_item_fulltext. Separate from the above because reading a paper is bounded by your assistant's context, not by recall. | | attachment_priority | ["pdf", "html", "other"] | Order in which attachment kinds are tried when an item has several readable files. |

attachment_priority exists for the case where you have converted a paper to clean Markdown yourself and attached it next to the original PDF. By default the PDF still wins; listing "markdown" first makes your converted copy the one that gets read and indexed. Valid entries are pdf, html, markdown, text and other. other is a catch-all matching every kind not named elsewhere in the list, so the default sweeps Markdown and plain text into one bucket where the larger file wins. Omitting other means anything unlisted is never chosen.

Changing this setting marks affected items for re-extraction, so a following zotero-mcp update-db refreshes text that came from a now-deprioritized attachment rather than leaving stale embeddings behind.

To read one specific attachment regardless of priority, pass that attachment's own key to zotero_get_item_fulltext (find it with zotero_get_item_children) — an attachment key bypasses the priority order and reads exactly that file.

🖥️ Setup & Usage

Full documentation is available at Zotero MCP docs.

Requirements

• Python 3.10+
• Zotero 7+ (for local API with full-tex