zotero-mcp

Supports Claude Code, Cursor, Mcp

General Issues

• No results found: Ensure Zotero is running and the local API is enabled. You need to toggle on Allow other applications on this computer to communicate with Zotero in Zotero preferences.
• 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
• Local library limitations: Some functionality (tagging, library modifications) may not work with local JS API. Consider using web library setup for full functionality. (See the docs for more info.)
• Installation/search option switching issues: Database problems from changing install methods or search options can often be resolved with zotero-mcp update-db --force-rebuild

Semantic Search Issues

• "Missing required environment variables" when running update-db: Run zotero-mcp setup to configure your environment, or the CLI will automatically load settings from your MCP client config (e.g., Claude Desktop)
• ChromaDB / stale embedding model errors: If you changed embedding models and see 404 errors (e.g., text-embedding-004 is not found), run zotero-mcp update-db --force-rebuild to recreate the collection with your current model. If that doesn't work, delete ~/.config/zotero-mcp/chroma_db/ and rebuild.
• Database update takes long: By default, update-db is fast (metadata-only). For comprehensive indexing with full-text, use --fulltext flag. Use --limit parameter for testing: zotero-mcp update-db --limit 100
• Semantic search returns no results: Ensure the database is initialized with zotero-mcp update-db and check status with zotero-mcp db-status
• Limited search quality: For better semantic search results, use zotero-mcp update-db --fulltext to index full-text content (requires local Zotero setup)
• OpenAI/Gemini API errors: Verify your API keys are correctly set and have sufficient credits/quota

Update Issues

• Update command fails: Check your internet connection and try zotero-mcp update --force
• Configuration lost after update: The update process preserves configs automatically, but check ~/.config/zotero-mcp/ for backup files

🧠 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

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

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.