home / mcp / zotero mcp server

Zotero MCP Server

Zotero MCP: Connects your Zotero research library with Claude and other AI assistants via the Model Context Protocol to discuss papers, get summaries, analyze citations, and more.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "54yyyu-zotero-mcp": {
      "command": "zotero-mcp",
      "args": [
        "serve"
      ],
      "env": {
        "ZOTERO_LOCAL": "true",
        "GEMINI_API_KEY": "YOUR_GEMINI_KEY",
        "OPENAI_API_KEY": "YOUR_OPENAI_KEY",
        "ZOTERO_API_KEY": "YOUR_API_KEY",
        "GEMINI_BASE_URL": "https://gemini.googleapis.com",
        "OPENAI_BASE_URL": "https://api.openai.com/v1",
        "ZOTERO_LIBRARY_ID": "YOUR_LIBRARY_ID",
        "ZOTERO_LIBRARY_TYPE": "user",
        "GEMINI_EMBEDDING_MODEL": "gemini-embedding-001",
        "OPENAI_EMBEDDING_MODEL": "text-embedding-3-small",
        "ZOTERO_EMBEDDING_MODEL": "default"
      }
    }
  }
}

Zotero MCP connects your Zotero research library with AI assistants such as Claude, ChatGPT, and others, enabling you to search, summarize, and extract insights from your library locally or via a web API.

How to use

You use Zotero MCP by running the local server on your machine and connecting an MCP client (for example Claude Desktop, ChatGPT, Cherry Studio, or Chorus) to it. You can perform semantic searches over your Zotero library, retrieve item metadata and full text when available, access notes and attachments, and extract PDF annotations for easy review. The server supports both offline local access and web-based access for remote collaboration.

How to install

Prerequisites you need before starting:

Choose a installation method and run the commands shown to install and set up Zotero MCP.

Default installation (recommended) using uv

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

Alternative installation using Python package manager

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

Alternative installation using Python via a wrapper (pipx) that keeps it isolated

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

Updating your installation while preserving configuration

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

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

Configuration and usage notes

Zotero MCP can be run locally for offline access or exposed via a web API for remote access. You can configure semantic search with different embedding models and update frequencies. The setup flow includes optional semantic search configuration and choices about how often the library index updates.

For local CLI usage and remote clients, you typically start the MCP server and then connect your client to the served endpoint or socket. Use the client to issue search queries, request metadata, export citations, or retrieve full text where Zotero provides access.

Advanced configuration and environment variables

Configure your server to use the local Zotero API or the web API, and set environment variables to control embedding models, API keys, and database paths.

Key environment variables you may encounter include the following. Use placeholders where values are not provided in your setup.

PDF annotation extraction

Zotero MCP includes advanced PDF annotation extraction, allowing you to process annotations directly from PDFs, search through PDF annotations, and work with image annotations. It integrates with Zotero’s native annotation system.

For best results, install the Better BibTeX plugin for Zotero, as annotation-related features are enhanced when the plugin is present.

When you use PDF annotation features for the first time, the necessary tools will download automatically.

Troubleshooting

General issues you may encounter and how to resolve them include verifying that Zotero is running and the local API is enabled, checking API keys and library IDs for web API access, and ensuring you are on a compatible Zotero version for local full-text access.

Semantic search related tips cover common issues such as missing environment variables, deprecation warnings, and indexing status checks.

If update commands fail, verify your internet connection and consider forcing an update. Preserve configurations by default, but review the MCP client config directory if you notice discrepancies after updates.

Support and license

If you find Zotero MCP useful, consider supporting its development.

License: MIT

Available tools

zotero_semantic_search

AI-powered similarity search with embedding models

zotero_update_search_database

Manually update the semantic search database

zotero_get_search_database_status

Check database status and configuration

zotero_search_items

Search your library by keywords

zotero_advanced_search

Perform complex searches with multiple criteria

zotero_get_collections

List collections

zotero_get_collection_items

Get items in a collection

zotero_get_tags

List all tags

zotero_get_recent

Get recently added items

zotero_search_by_tag

Search your library using custom tag filters

zotero_get_item_metadata

Get detailed metadata (BibTeX export available)

zotero_get_item_fulltext

Get full text content for items where available

zotero_get_item_children

Get attachments and notes for an item

zotero_get_annotations

Get annotations including direct PDF extraction

zotero_get_notes

Retrieve notes from your Zotero library

zotero_search_notes

Search notes and annotations including PDF-extracted content

zotero_create_note

Create a new note for an item (beta feature)