Zotero MCP: Chat with your Research Library—Local or Web—in Claude, ChatGPT, and more.

Zotero MCP seamlessly connects your Zotero research library with ChatGPT, Claude, and other AI assistants (e.g., Cherry Studio, Chorus, Cursor) via the Model Context Protocol. Review papers, get summaries, analyze citations, extract PDF annotations, and more!

🔀 Fork Changes (vs 54yyyu/zotero-mcp)

This is a personal fork. The main additions over the upstream repo:

✍️ 10 New Write Tools (require Web API credentials)

Tool	What it does
`zotero_add_items_by_doi`	Import papers by DOI — metadata fetched from CrossRef
`zotero_add_items_by_arxiv`	Import preprints by arXiv ID, URL, or DOI prefix
`zotero_add_item_by_url`	Save a webpage as a Zotero item
`zotero_update_item`	Update any field on an existing item
`zotero_update_note`	Replace the HTML content of an existing note
`zotero_create_collection`	Create a top-level or nested collection
`zotero_move_items_to_collection`	Add or remove items from a collection
`zotero_update_collection`	Rename a collection or change its parent
`zotero_delete_collection`	Delete a collection (items inside are kept)
`zotero_delete_items`	Move items to trash (recoverable)
`zotero_find_and_attach_pdfs`	Find OA PDFs for existing items via Unpaywall and attach them
`zotero_add_linked_url_attachment`	Add a linked URL attachment to an existing item

🔄 Auto-Detect Local vs Web API

No need to set ZOTERO_LOCAL manually. When unset, the server tries the local Zotero desktop first and falls back to the Web API automatically. Set ZOTERO_LOCAL=true/false only to force a specific mode.

🔑 Auto-Load Credentials from AI Tool Configs

If ZOTERO_API_KEY / ZOTERO_LIBRARY_ID are already set in your MCP client config, the server picks them up automatically — no separate .env file needed:

Tool	Config file	Key path
Claude Code	`~/.claude/settings.json`	`mcpServers.zotero.env`
OpenCode	`~/opencode.jsonc`	`mcp.servers.zotero.env`
Codex CLI	`~/.codex/config.toml`	`mcp_servers.zotero.env`

🐛 Bug Fix

zotero_create_note — was returning "0" as the new item key; now returns the correct key

🗑️ Removed

zotero_create_annotation — removed (unreliable with the local API)

✨ Features

🧠 AI-Powered Semantic Search

Vector-based similarity search over your entire research library
Multiple embedding models: Default (free), OpenAI, and Gemini options
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
NEW: Semantic search for conceptual and topic-based discovery

📚 Access Your Content

Retrieve detailed metadata for any item
Get full text content (when available)
Access attachments, notes, and child items

📝 Work with Annotations & Notes

Extract and search PDF annotations directly
Access Zotero's native annotations
Create and update notes

✍️ Write & Organize Your Library

Import papers by DOI, arXiv ID, or URL — metadata fetched automatically
Update items — edit any field on existing library entries
Manage collections — create, rename, re-parent, and delete collections
Move items — add or remove items from collections in bulk
Delete items — move items to trash (recoverable)
Batch tag — add or remove tags across multiple items at once

🔄 Easy Updates

Smart update system that detects your installation method (uv, pip, conda, pipx)
Configuration preservation - all settings maintained during updates
Version checking and automatic update notifications

🌐 Flexible Access Methods

Local method for offline access (no API key needed)
Web API for cloud library access
Perfect for both local research and remote collaboration

🚀 Quick Install

Default Installation

Installing via uv (recommended)

uv tool install git+https://github.com/Galaxy-Dawn/zotero-mcp.git
zotero-mcp setup  # Auto-configure (Claude Desktop supported)

Installing via pip

pip install git+https://github.com/Galaxy-Dawn/zotero-mcp.git
zotero-mcp setup  # Auto-configure (Claude Desktop supported)

Installing via pipx

pipx install git+https://github.com/Galaxy-Dawn/zotero-mcp.git
zotero-mcp setup  # Auto-configure (Claude Desktop supported)

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

Enable Write Tools (Optional)

Read-only tools work out of the box with the local API. To unlock import, edit, and collection management tools, add your Zotero Web API credentials:

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

Or set environment variables directly:

export ZOTERO_API_KEY=your_api_key
export ZOTERO_LIBRARY_ID=your_library_id
# Optional: set UNPAYWALL_EMAIL to enable OA PDF auto-attach
export UNPAYWALL_EMAIL=your_email@example.com
# Optional: set UNSAFE_OPERATIONS to enable delete tools
export UNSAFE_OPERATIONS=all

Auto-loading: If you use Claude Code, OpenCode, or Codex CLI, credentials already set in your MCP config are loaded automatically — no separate setup needed. See Advanced Configuration for details.

🧠 Semantic Search

Zotero MCP now includes powerful AI-powered semantic search capabilities that let you find research based on concepts and meaning, not just keywords.

Setup Semantic Search

During setup or separately, configure semantic search:

# Configure during initial setup (recommended)
zotero-mcp setup

# 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

Using Semantic Search

After setup, initialize your search database:

# 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

# Use your custom zotero.sqlite path
zotero-mcp update-db --fulltext --db-path "/Your_custom_path/zotero.sqlite"

If you have embedding confilts when using `zotero-mcp update-db --fulltext`, use `--force-rebuild` to force a 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.

🖥️ Setup & Usage

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.

For Claude Desktop (example MCP client)

Configuration

After installation, either:

Auto-configure (recommended):
```
zotero-mcp setup
```

Manual configuration: Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "zotero": {
      "command": "zotero-mcp",
      "env": {
        "ZOTERO_API_KEY": "your_api_key",
        "ZOTERO_LIBRARY_ID": "your_library_id",
        "ZOTERO_LIBRARY_TYPE": "user",
        "UNPAYWALL_EMAIL": "your_email@example.com",
        "UNSAFE_OPERATIONS": "all"
      }
    }
  }
}

ZOTERO_API_KEY and ZOTERO_LIBRARY_ID are required for write tools. The server auto-detects local vs web — no need to set ZOTERO_LOCAL.

Usage

Start Zotero desktop (make sure local API is enabled in preferences)
Launch Claude Desktop
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)

For Cherry Studio

Configuration

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

{
  "mcpServers": {
    "zotero": {
      "name": "zotero",
      "type": "stdio",
      "isActive": true,
      "command": "zotero-mcp",
      "args": [],
      "env": {
        "ZOTERO_API_KEY": "your_api_key",
        "ZOTERO_LIBRARY_ID": "your_library_id",
        "ZOTERO_LIBRARY_TYPE": "user",
        "UNPAYWALL_EMAIL": "your_email@example.com",
        "UNSAFE_OPERATIONS": "all"
      }
    }
  }
}

Then click "Save".

Cherry Studio also provides a visual configuration method for general settings and tools selection.

🔧 Advanced Configuration

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

Auto-Loading Credentials from AI Tool Configs

If you have Zotero credentials configured in your AI tool's MCP settings, the server will load them automatically — no separate .env file needed:

Tool	Config file	Key path
Claude Code	`~/.claude/settings.json`	`mcpServers.zotero.env`
OpenCode	`~/opencode.jsonc`	`mcp.servers.zotero.env`
Codex CLI	`~/.codex/config.toml`	`mcp_servers.zotero.env`

Environment variables already set in the shell always take precedence.

Environment Variables

Zotero Connection:

ZOTERO_LOCAL: true = always use local Zotero desktop; false = always use Web API; unset = auto-detect (tries local first, falls back to web)
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)

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)

PDF Auto-Attach:

UNPAYWALL_EMAIL: Your email for Unpaywall API (free, required for PDF auto-attach via zotero_find_and_attach_pdfs or add_items_by_doi with attach_pdf=true)
UNSAFE_OPERATIONS: Set to items to enable zotero_delete_items; set to all to also enable zotero_delete_collection

Command-Line Options

# Run the server directly
zotero-mcp serve

# Specify transport method
zotero-mcp serve --transport stdio|streamable-http|sse

# 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

# Updates and maintenance
zotero-mcp update                          # Update to latest version
zotero-mcp update --check-only             # Check for updates without installing
zotero-mcp update --force                  # Force update even if up to date

# Semantic search database management
zotero-mcp update-db                       # Update semantic search database (fast, metadata-only)
zotero-mcp update-db --fulltext             # Update with full-text extraction (comprehensive but slower)
zotero-mcp update-db --force-rebuild       # Force complete database rebuild
zotero-mcp update-db --fulltext --force-rebuild  # Rebuild with full-text extraction
zotero-mcp update-db --fulltext --db-path "your_path_to/zotero.sqlite" # Customize your zotero database path
zotero-mcp db-status                       # Show database status and info

# General
zotero-mcp version                         # Show current version

📑 PDF Annotation Extraction

Zotero MCP includes advanced PDF annotation extraction capabilities:

Direct PDF Processing: Extract annotations directly from PDF files, even if they're not yet indexed by Zotero
Enhanced Search: Search through PDF annotations and comments
Image Annotation Support: Extract image annotations from PDFs
Seamless Integration: Works alongside Zotero's native annotation system

For optimal annotation extraction, it is highly recommended to install the Better BibTeX plugin for Zotero. The annotation-related functions have been primarily tested with this plugin and provide enhanced functionality when it's available.

The first time you use PDF annotation features, the necessary tools will be automatically downloaded.

📚 Available Tools

🧠 Semantic Search 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

🔍 Search Tools

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

📚 Content Tools

zotero_get_item_metadata: Get detailed metadata (supports BibTeX export via format="bibtex")
zotero_get_item_fulltext: Get full text content
zotero_get_item_children: Get attachments and notes

📝 Annotation & Notes Tools

zotero_get_annotations: Get annotations (including direct PDF extraction)
zotero_get_notes: Retrieve notes from your Zotero library
zotero_search_notes: Search in notes and annotations (including PDF-extracted)
zotero_create_note: Create a new note for an item

✍️ Write Tools (require Web API credentials)

Import

zotero_add_items_by_doi: Import papers by DOI — fetches metadata from CrossRef automatically
zotero_add_items_by_arxiv: Import preprints by arXiv ID (bare ID, arXiv: prefix, full URL, or DOI prefix all accepted)
zotero_add_item_by_url: Save a webpage as a Zotero item — title extracted from og:title or <title>
zotero_find_and_attach_pdfs: Find and attach OA PDFs for existing items via Unpaywall (requires UNPAYWALL_EMAIL)
zotero_add_linked_url_attachment: Add a linked URL attachment to an existing item

Edit

zotero_update_item: Update any field on an existing library item
zotero_update_note: Replace the HTML content of an existing note

Collections

zotero_create_collection: Create a new top-level or nested collection
zotero_move_items_to_collection: Add or remove items from a collection
zotero_update_collection: Rename a collection or change its parent
zotero_delete_collection: Permanently delete a collection (items inside are kept)

Deletion

zotero_delete_items: Move one or more items to trash (recoverable)

🏷️ Tag & Library Tools

zotero_batch_update_tags: Add or remove tags across multiple items matching a query
zotero_list_libraries: List all accessible libraries (user, group, RSS feeds)
zotero_switch_library: Switch the active library context for all subsequent calls
zotero_list_feeds: List RSS feed subscriptions (local mode only)
zotero_get_feed_items: Get items from a specific RSS feed (local mode only)

🔍 Troubleshooting

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 warnings: Update to the latest version - deprecation warnings have been fixed
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

📄 License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 164 Commits
.github		.github
docs		docs
public		public
src/zotero_mcp		src/zotero_mcp
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
SESSION_LOG.md		SESSION_LOG.md
pyproject.toml		pyproject.toml
smithery.yaml		smithery.yaml

Folders and files

Latest commit

History

Repository files navigation

Zotero MCP: Chat with your Research Library—Local or Web—in Claude, ChatGPT, and more.

🔀 Fork Changes (vs 54yyyu/zotero-mcp)

✍️ 10 New Write Tools (require Web API credentials)

🔄 Auto-Detect Local vs Web API

🔑 Auto-Load Credentials from AI Tool Configs

🐛 Bug Fix

🗑️ Removed

✨ Features

🧠 AI-Powered Semantic Search

🔍 Search Your Library

📚 Access Your Content

📝 Work with Annotations & Notes

✍️ Write & Organize Your Library

🔄 Easy Updates

🌐 Flexible Access Methods

🚀 Quick Install

Default Installation

Installing via uv (recommended)

Installing via pip

Installing via pipx

Updating Your Installation

Enable Write Tools (Optional)

🧠 Semantic Search

Setup Semantic Search

Using Semantic Search

🖥️ Setup & Usage

For Claude Desktop (example MCP client)

Configuration

Usage

For Cherry Studio

Configuration

🔧 Advanced Configuration

Using Web API Instead of Local API

Auto-Loading Credentials from AI Tool Configs

Environment Variables

Command-Line Options

📑 PDF Annotation Extraction

📚 Available Tools

🧠 Semantic Search Tools

🔍 Search Tools

📚 Content Tools

📝 Annotation & Notes Tools

✍️ Write Tools (require Web API credentials)

🏷️ Tag & Library Tools

🔍 Troubleshooting

General Issues

Semantic Search Issues

Update Issues

📄 License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages