Zotero MCP: Connect Your Research Library with Claude and Other AI Assistants


Zotero


Claude


MCP

Zotero MCP is a tool that smoothly links your Zotero research library with Claude and other AI assistants (like Cherry Studio and Cursor) through the Model Context Protocol. With it, you can discuss research papers, get summaries, analyze citations, pull out PDF annotations, and much more!

✨ What Zotero MCP Can Do

🧠 AI-Powered Semantic Search

  • Vector-based similarity search: This means it can find research in your entire library that’s conceptually similar to what you’re looking for, not just matching exact words.
  • Multiple embedding models: You can choose from different models. The default one is free, and there are options for OpenAI and Gemini too.
  • Intelligent results: When it finds matches, it shows how similar they are and why they’re a good fit based on context.
  • Auto-updating database: The system that stores your search information can update itself on a schedule you set.

🔍 Search Through Your Library

  • Find papers, articles, and books by their title, author, or what’s inside them.
  • Do complex searches using more than one criteria (like looking for papers by a specific author on a certain topic).
  • Browse through your collections, tags, and the items you’ve added recently.
  • NEW: Semantic search lets you discover research based on ideas and topics, not just keywords.

📚 Get to Your Content

  • Get detailed information (like publication date, journal name) for any item in your library.
  • Access the full text of items when it’s available.
  • View attachments (like PDFs), notes, and related child items.

📝 Work with Annotations

  • Pull out and search through annotations you’ve made in PDFs directly.
  • Access the annotations you’ve created using Zotero’s own tools.
  • Create new notes and annotations and update existing ones.

🔄 Easy Updates

  • Smart update system: It figures out how you installed it (whether using uv, pip, conda, or pipx) and updates accordingly.
  • Configuration preservation: All your settings stay the same when you update.
  • Version checking: It tells you when there’s a new version and can update automatically.

🌐 Flexible Ways to Access

  • Local method: Use it without an internet connection (no API key needed).
  • Web API: Access your library from the cloud.
  • Great for both working on research locally and collaborating with others remotely.

🚀 Quick Installation Guide

Installing with Smithery

If you want to install Zotero MCP for Claude Desktop automatically using Smithery, just run this command:

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

Manual Installation

Installing with uv

uv is a tool for managing Python packages. Here’s how to use it:

uv tool install "git+https://github.com/54yyyu/zotero-mcp.git"
zotero-mcp setup  # This automatically configures it for Claude Desktop

Installing with pip

pip is another common Python package manager. Use these commands:

pip install git+https://github.com/54yyyu/zotero-mcp.git
zotero-mcp setup  # This automatically configures it for Claude Desktop

Updating Your Installation

It’s important to keep Zotero MCP up to date. Here’s how:

# Check if there's an update available
zotero-mcp update --check-only

# Update to the latest version (your settings will stay the same)
zotero-mcp update

🧠 Semantic Search: Find Research by Ideas, Not Just Words

Zotero MCP now has a powerful semantic search feature. This means instead of just looking for exact keywords, it can understand the ideas behind your search and find research that’s related in meaning.

Setting Up Semantic Search

You can set up semantic search either during the initial setup or later:

# Set it up during the first-time setup (recommended)
zotero-mcp setup

# Or set up just the semantic search part separately
zotero-mcp setup --semantic-config-only

Available Embedding Models:

  • Default (all-MiniLM-L6-v2): This one is free and runs on your own computer. It works well for most everyday research needs.
  • OpenAI: Gives better results but requires an API key. It uses models like text-embedding-3-small or text-embedding-3-large.
  • Gemini: Also provides high-quality results and needs an API key. It uses models such as models/text-embedding-004 or other experimental ones.

Update Frequency Options:

  • Manual: The database only updates when you run the command zotero-mcp update-db.
  • Auto on startup: It updates the database every time the server starts.
  • Daily: Updates once every day automatically.
  • Every N days: You can set a custom number of days between updates.

Using Semantic Search

After setting it up, you need to create your search database:

# Build the semantic search database
zotero-mcp update-db

# Check how the database is doing
zotero-mcp db-status

Examples of Semantic Search Queries in Claude:

  • “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 shows how similar each result is to your query and finds papers based on understanding the ideas, not just matching words.

🖥️ Setting Up and Using Zotero MCP

You can find full documentation at Zotero MCP docs.

What You Need

  • Python 3.10 or newer
  • Zotero 7 or newer (to use the local API and get full-text access)
  • Claude Desktop or another compatible AI assistant

For Claude Desktop

Configuration

After installing, you can either:

  1. Auto-configure (this is the recommended way):

    zotero-mcp setup

  2. Manual configuration:
    Add this to your claude_desktop_config.json file:

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

How to Use It

  1. Start the Zotero desktop app. Make sure the local API is turned on in the preferences.
  2. Open Claude Desktop.
  3. Find the Zotero-MCP tool in Claude Desktop’s tools menu.

Example things you can ask:

  • “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” (uses semantic search)
  • “Research that relates to the intersection of AI and healthcare” (uses semantic search)
  • “Papers that discuss topics similar to this abstract: [paste text]” (uses semantic search)

For Cherry Studio

Configuration

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

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

Then click “Save”.

Cherry Studio also has a visual way to configure general settings and choose which tools to use.

🔧 Advanced Configuration Options

Using the Web API Instead of the Local API

If you want to access your Zotero library through the web API (this is useful if you’re using it remotely), use this command:

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

Environment Variables

Environment variables are like settings that control how Zotero MCP works.

Zotero Connection:

  • ZOTERO_LOCAL=true: Use the local Zotero API (it’s set to false by default).
  • ZOTERO_API_KEY: Your Zotero API key (needed for the web API).
  • ZOTERO_LIBRARY_ID: Your Zotero library ID (needed for the web API).
  • ZOTERO_LIBRARY_TYPE: The type of library (either “user” or “group”; it’s “user” by default).

Semantic Search:

  • ZOTERO_EMBEDDING_MODEL: Which embedding model to use (options are “default”, “openai”, “gemini”).
  • OPENAI_API_KEY: Your OpenAI API key (needed if using OpenAI embeddings).
  • OPENAI_EMBEDDING_MODEL: The name of the OpenAI model (like “text-embedding-3-small” or “text-embedding-3-large”).
  • GEMINI_API_KEY: Your Gemini API key (needed if using Gemini embeddings).
  • GEMINI_EMBEDDING_MODEL: The name of the Gemini model (like “models/text-embedding-004”).

Command-Line Options

These are commands you can type to control Zotero MCP:

# Run the server directly
zotero-mcp serve

# Choose how the server sends and receives data
zotero-mcp serve --transport stdio|streamable-http|sse

# Setup and configuration help
zotero-mcp setup --help                    # Learn more about setup options
zotero-mcp setup --semantic-config-only    # Only set up semantic search
zotero-mcp setup-info                      # Show where it's installed and config info for MCP clients

# Updates and maintenance
zotero-mcp update                          # Update to the latest version
zotero-mcp update --check-only             # See if there's an update without installing it
zotero-mcp update --force                  # Update even if it says you're up to date

# Semantic search database management
zotero-mcp update-db                       # Update the semantic search database
zotero-mcp update-db --force-rebuild       # Completely rebuild the database from scratch
zotero-mcp db-status                       # Show how the database is doing and its settings

# General information
zotero-mcp version                         # Show which version you're using

📑 Extracting PDF Annotations

Zotero MCP has advanced features for getting annotations from PDFs:

  • Direct PDF Processing: It can pull out annotations directly from PDF files, even if Zotero hasn’t indexed them yet.
  • Enhanced Search: You can search through the annotations and comments you’ve made in PDFs.
  • Image Annotation Support: It can get image annotations from PDFs too.
  • Seamless Integration: Works well with Zotero’s own annotation system.

For the best results when extracting annotations, it’s strongly recommended to install the Better BibTeX plugin for Zotero. The annotation features have been mostly tested with this plugin, and it adds more functionality when it’s installed.

The first time you use the PDF annotation features, Zotero MCP will automatically download the tools it needs.

📚 Tools Available in Zotero MCP

🧠 Semantic Search Tools

  • zotero_semantic_search: Uses AI to find similar research using embedding models.
  • zotero_update_search_database: Lets you manually update the semantic search database.
  • zotero_get_search_database_status: Checks how the database is doing and its settings.

🔍 Search Tools

  • zotero_search_items: Searches your library using keywords.
  • zotero_advanced_search: Does more complex searches with multiple conditions.
  • zotero_get_collections: Lists all your collections.
  • zotero_get_collection_items: Gets all the items in a specific collection.
  • zotero_get_tags: Shows all the tags you’ve used.
  • zotero_get_recent: Gets the items you’ve added recently.
  • zotero_search_by_tag: Searches your library using custom tag filters.

📚 Content Tools

  • zotero_get_item_metadata: Gets detailed information about an item. You can use format="bibtex" to get a BibTeX citation.
  • zotero_get_item_fulltext: Gets the full text of an item when available.
  • zotero_get_item_children: Gets attachments and notes related to an item.

📝 Annotation & Notes Tools

  • zotero_get_annotations: Gets annotations (including those extracted directly from PDFs).
  • zotero_get_notes: Retrieves notes from your Zotero library.
  • zotero_search_notes: Searches through your notes and annotations (including those from PDFs).
  • zotero_create_note: Creates a new note for an item (this is a beta feature, meaning it’s still being tested).

🔍 Troubleshooting Common Issues

General Problems

  • No results found: Make sure Zotero is running and that the local API is turned on in Zotero’s preferences.
  • Can’t connect to library: If you’re using the web API, check that your API key and library ID are correct.
  • Full text not available: You need Zotero 7 or newer to get full-text access using the local method.
  • Local library limitations: Some features (like adding tags or changing the library) might not work with the local JS API. For full functionality, consider using the web library setup. (You can find more info in the docs.)
  • Installation or search option issues: If you have problems after changing how you installed it or switching search options, try zotero-mcp update-db --force-rebuild to fix database issues.

Semantic Search Issues

  • “Missing required environment variables” when running update-db: Run zotero-mcp setup to configure your settings. The CLI can also automatically load settings from the Claude Desktop config.
  • ChromaDB warnings: Update to the latest version of Zotero MCP—these warnings about outdated code have been fixed.
  • Database update takes a long time: This is normal if you have a large library. For testing, you can use the --limit parameter: zotero-mcp update-db --limit 100 (this limits the update to 100 items).
  • Semantic search returns no results: Make sure the database is set up with zotero-mcp update-db and check its status with zotero-mcp db-status.
  • OpenAI/Gemini API errors: Check that your API keys are entered correctly and that you have enough credits or quota to use them.

Update Issues

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