zotero-mcp MCP工具

🚀 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)

Setup Semantic Search

During setup or separately, configure semantic search:

```bash

Configure during initial setup (recommended)

zotero-mcp setup

Build the semantic search database (fast, metadata-only)

zotero-mcp update-db

Build with full-text extraction (slower, more comprehensive)

zotero-mcp update-db --fulltext

If you have embedding conflicts or changed models, force a rebuild

zotero-mcp update-db --force-rebuild

🖥️ Setup & Usage

Full documentation is available at Zotero MCP docs.

Requirements - Python 3.10+ - Zotero 7+ (for local API with full-text access) - An MCP-compatible client (e.g., Claude Desktop, ChatGPT Developer Mode, Cherry Studio, Chorus)

For ChatGPT setup: see the Getting Started guide.

Setup and configuration

zotero-mcp setup --help # Get help on setup options zotero-mcp setup --semantic-config-only # Configure only semantic search zotero-mcp setup-info # Show installation path and config info for MCP clients

For Claude Desktop (example MCP client)

#### Configuration After installation, either:

1. Auto-configure (recommended):

   zotero-mcp setup
   

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

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

Usage

1. Start Zotero desktop (make sure local API is enabled in preferences)
2. Launch Claude Desktop
3. Access the Zotero-MCP tool through Claude Desktop's tools interface

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

📊 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

Optional Extras

Heavy ML/PDF dependencies are separated into optional extras so the base install stays fast and small:

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:

```bash

Update to latest version (preserves all configurations)

zotero-mcp update ```

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)

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

🔧 Advanced Configuration

Environment Variables

Zotero Connection: - ZOTERO_LOCAL=true: Use the local Zotero API (default: false) - ZOTERO_API_KEY: Your Zotero API key (for web API) - ZOTERO_LIBRARY_ID: Your Zotero library ID (for web API) - ZOTERO_LIBRARY_TYPE: The type of library (user or group, default: user) - ZOTERO_WEBDAV_URL: Optional WebDAV folder URL for direct attachment downloads in remote mode - ZOTERO_WEBDAV_USERNAME: Optional WebDAV username - ZOTERO_WEBDAV_PASSWORD: Optional WebDAV password

Semantic Search: - ZOTERO_EMBEDDING_MODEL: Embedding model to use (default, openai, gemini) - OPENAI_API_KEY: Your OpenAI API key (for OpenAI embeddings) - OPENAI_EMBEDDING_MODEL: OpenAI model name (text-embedding-3-small, text-embedding-3-large) - OPENAI_BASE_URL: Custom OpenAI endpoint URL (optional, for use with compatible APIs) - GEMINI_API_KEY: Your Gemini API key (for Gemini embeddings) - GEMINI_EMBEDDING_MODEL: Gemini model name (gemini-embedding-001) - GEMINI_BASE_URL: Custom Gemini endpoint URL (optional, for use with compatible APIs) - ZOTERO_DB_PATH: Custom zotero.sqlite path (optional)

Command-Line Options

```bash

⌨️ 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

Using Web API Instead of Local API

For accessing your Zotero library via the web API (useful for remote setups):

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

⌨️ CLI Mode (`zotero-cli`)

zotero-cli is a standalone terminal interface to your Zotero library. It uses the same tools as the MCP server but without needing an AI assistant — useful for quick lookups, shell scripts, and automation.

Use zotero-mcp when your AI client supports MCP (Claude Desktop, ChatGPT). Use zotero-cli for shell scripts, cron jobs, or agentic pipelines with shell access (e.g. Claude Code) — CLI commands cost far fewer tokens than MCP tool schemas and compose naturally with Unix pipes.

Both share the same configuration set up by zotero-mcp setup.

Quick reference

```bash

Integration Test Plan

A 45-point live integration test plan is included at docs/integration-test-plan.md. It's designed to be given to Claude in Claude Desktop, which will execute each test against your real Zotero library. Tests cover all tools, PDF attachment cascade, attach_mode, BetterBibTeX lookups, and multi-step showcase prompts. See the file for full instructions.

🔍 Troubleshooting