DOCSEARCHbyAlgolia
Submit Docs

Zotero MCP

repository·main·Indexed 26 days ago

https://github.com/54yyyu/zotero-mcp

A Model Context Protocol (MCP) server that connects Zotero research libraries to AI assistants like Claude and ChatGPT. It provides capabilities for semantic search, metadata retrieval, annotation extraction, and library management via AI or a standalone CLI. The server supports local read-only mode, hybrid mode for web API writes, and optional extras for PDF extraction and Scite citation intelligence.

Tokens
15.1K
Snippets
24
Records
102
Agent score
87%

What's inside zotero-mcp

  2. Persist configuration and ChromaDB in Docker

    main

    By default, configuration and the semantic index (ChromaDB) are stored inside the container at:

    • /home/app/.config/zotero-mcp/config.json
    • /home/app/.config/zotero-mcp/chroma_db/

    To prevent ChromaDB from being rebuilt every time the container restarts (e.g., after running zotero-mcp update-db), you must mount the configuration directory to a persistent volume or host path.

    docker run --rm \
  -v zotero-mcp-data:/home/app/.config/zotero-mcp \
  --env-file .env \
  ghcr.io/<owner>/zotero-mcp:latest

  3. Set up a tunnel for ChatGPT/OpenAI integration

    main

    Since ChatGPT web app does not support local MCPs natively, you must use a tunnel (like ngrok) to expose your local server via SSE.

    1. Start the Zotero MCP server using the sse transport:
      zotero-mcp serve --transport sse --host 0.0.0.0 --port 8000
    2. Start the ngrok tunnel in a separate terminal:
      ngrok http 8000
    3. Copy the HTTPS URL provided by ngrok (e.g., https://<random-string>.ngrok-free.app).
    zotero-mcp serve --transport sse --host 0.0.0.0 --port 8000

  4. Run Zotero MCP via Docker

    main

    Zotero MCP is available as multi-arch Docker images on GHCR. Use the -core tag for a lightweight install or the default/-all tag for full features (semantic search, PDF, scite).

    Common Docker Commands

    Default MCP server mode (stdio):

    docker run --rm ghcr.io/<owner>/zotero-mcp:latest

    MCP server mode with explicit transport (e.g., SSE):

    docker run --rm ghcr.io/<owner>/zotero-mcp:latest serve --transport streamable-http --host 0.0.0.0 --port 8000

    Standalone CLI mode: Set ZOTERO_APP=cli to use the CLI instead of the server.

    docker run --rm -e ZOTERO_APP=cli ghcr.io/<owner>/zotero-mcp:latest search "machine learning"

    Persistence: To persist configuration and the ChromaDB database across container restarts, mount /home/app/.config/zotero-mcp to a volume.

    docker run --rm -v zotero-mcp-data:/home/app/.config/zotero-mcp --env-file .env ghcr.io/<owner>/zotero-mcp:latest

  5. Cleanup Rules for Test Items

    main

    When performing write operations or adding items during testing, follow these cleanup protocols to prevent library clutter:

    • New Items: Every NEW item created (via DOI, URL, or file) MUST be tagged with _MCP-test-to-delete.
    • Existing Items: Do NOT add the cleanup tag to existing items being modified (e.g., title updates or tag changes).
    • Temporary Tags: Any tags added to existing items (e.g., mcp-test-verified) must be removed at the end of the testing phase to restore the item to its original state.
    • Collections: Name test collections with the prefix "MCP Test".
    • Final Cleanup: To remove all test artifacts, filter Zotero by the tag _MCP-test-to-delete, move those items to the Trash, and delete any collections containing "MCP Test" in their name.

  6. Configure Zotero MCP Connector in ChatGPT.com

    main

    Once a tunnel is running, connect it to ChatGPT:

    1. In ChatGPT, go to Settings > Connectors.
    2. Enable Developer Mode via the Advanced... button.
    3. Click Create and fill in:
      • Name: Zotero MCP
      • Description: Search and retrieve documents from a local Zotero library.
      • MCP Server URL: Combine your ngrok URL, /sse/ (with trailing slash), and a unique session_id (UUIDv4).
        • Format: https://<YOUR_NGROK_URL>.ngrok-free.app/sse/?session_id=<YOUR_UUID>
      • Authentication: No authentication
    4. Tick I trust this application and click Create.
    5. Important: In the tool list, turn all "Edit" sliders to Off to ensure the tools enable in Developer Mode.
    6. To use in chats, start a new chat, click the "plus" icon, and select Deep Research mode, then enable Zotero-MCP as a source.

  7. Configure Zotero MCP via Web API (Remote Mode)

    main

    If you need to access your library remotely without the Zotero desktop app running locally, use the --no-local flag during setup to bypass the local API requirement.

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

  8. Extract PDF annotations

    main

    Zotero MCP supports advanced PDF annotation extraction, including direct processing of PDF files even if they are not yet indexed by Zotero. It supports searching through annotations, comments, and image annotations.

    Requirements & Recommendations:

    • Better BibTeX Plugin: It is highly recommended to install the Better BibTeX plugin for Zotero. Annotation-related functions are primarily tested with this plugin and provide enhanced functionality when available.
    • Automatic Setup: The first time you use PDF annotation features, the necessary tools will be automatically downloaded.

  9. Install Zotero MCP optional extras

    main

    To add advanced features like semantic search, PDF extraction, or Scite intelligence, install the corresponding extras using pip or uv:

    • semantic: Vector-based similarity search (requires ChromaDB and embedding models).
    • pdf: PDF outline extraction and EPUB annotation support.
    • scite: Scite citation intelligence (tallies and retraction alerts).
    • all: Installs all the above features.

    Note: When using uv, use quotes around the package name to ensure the shell handles the brackets correctly.

    # Full install with all features using uv
uv tool install "zotero-mcp-server[all]"

# Just semantic search using uv
uv tool install "zotero-mcp-server[semantic]"

# Using pip for specific extras
pip install "zotero-mcp-server[semantic]"
pip install "zotero-mcp-server[pdf]"
pip install "zotero-mcp-server[scite]"
pip install "zotero-mcp-server[all]"

  10. Configure Zotero MCP for Claude Desktop or Claude Code

    main

    You can configure the Zotero MCP server for Claude clients using auto-configuration or manual JSON editing.

    Auto-configure (Recommended)

    Run the following command in your terminal:

    zotero-mcp setup

    Manual Configuration

    Add the server definition to your configuration file:

    • Claude Desktop: claude_desktop_config.json
    • Claude Code: ~/.claude.json

    Local Read-Only Mode

    Use only ZOTERO_LOCAL: "true". This mode is fast but does not support write operations.

    Hybrid Mode (Fast Local Reads + Web API Writes)

    To enable writing (e.g., adding notes, changing tags), keep ZOTERO_LOCAL: "true" and provide your Zotero Web API credentials:

    1. Generate an API key at zotero.org/settings/security.
    2. Find your numeric userID on the same page.
    3. If using a group library, set ZOTERO_LIBRARY_TYPE: "group" and use the group's ID.
    {
  "mcpServers": {
    "zotero": {
      "command": "zotero-mcp",
      "env": {
        "ZOTERO_LOCAL": "true",
        "ZOTERO_API_KEY": "YOUR_API_KEY",
        "ZOTERO_LIBRARY_ID": "YOUR_LIBRARY_ID"
      }
    }
  }
}

  11. Add items by DOI with automatic PDF attachment

    main

    You can add papers to Zotero using their DOI. The system attempts to automatically attach an open-access PDF using a cascade of sources:

    1. Unpaywall (Gold Open Access)
    2. arXiv (via CrossRef metadata)
    3. PubMed Central (via NCBI ID converter)

    If no open-access PDF is found, the tool will return a message stating "no open-access PDF found" rather than an error.

  12. Integrate Zotero MCP with Chorus.sh

    main

    To use Zotero MCP with Chorus.sh:

    1. Find your installation path: Run zotero-mcp setup-info to get the exact path.
    2. Configure in Chorus.sh preferences:
      • Command: The full path to your zotero-mcp installation.
      • Arguments: Leave empty.
      • Environment (JSON): Provide your environment configuration as a single-line JSON string.

    Example Environment JSON:

    {"ZOTERO_LOCAL": "true"}