The Zotero MCP server allows AI assistants like Claude to interact with your Zotero research library via the Model Context Protocol. With this server, you can:
Search: Find items using simple queries or advanced criteria, and access recently added items
Access Content: Retrieve detailed metadata, full text, attachments, notes, and annotations (including direct PDF extraction)
Manage Collections: List all collections and get items within specific collections
Work with Tags: View all tags and perform batch updates to tags across multiple items
Create Content: Add new notes to items
Flexible Setup: Configure with environment variables and command-line options for local or web API access
Connects to your Zotero research library, allowing you to search for papers, articles and books, retrieve metadata, access full-text content, and browse collections, tags, and recent additions.
Zotero MCP: Your Research Library in Claude
Zotero MCP seamlessly connects your Zotero research library with Claude and other AI assistants (Cherry Studio, Cursor, etc.) via the Model Context Protocol. Discuss papers, get summaries, analyze citations, extract PDF annotations, and more!
✨ 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
- Extract and search PDF annotations directly
- Access Zotero's native annotations
- Create and update notes and annotations
🔄 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
Installing via pip
Installing via Smithery
To install Zotero MCP for Claude Desktop automatically via Smithery:
Updating Your Installation
Keep zotero-mcp up to date with the smart update command:
🧠 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:
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
ortext-embedding-3-large
) - Gemini: Better quality, requires API key (
models/text-embedding-004
or experimental models)
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:
Example Semantic 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 provides similarity scores and finds papers based on conceptual understanding, not just keyword matching.
🖥️ Setup & Usage
Full documentation is available at Zotero MCP docs.
Requirements
- Python 3.10+
- Zotero 7+ (for local API with full-text access)
- Claude Desktop or compatible AI assistant
For Claude Desktop
Configuration
After installation, either:
- Auto-configure (recommended):
- Manual configuration:
Add to your
claude_desktop_config.json
:
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:
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):
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)
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)GEMINI_API_KEY
: Your Gemini API key (for Gemini embeddings)GEMINI_EMBEDDING_MODEL
: Gemini model name (models/text-embedding-004, etc.)
Command-Line Options
📑 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 modelszotero_update_search_database
: Manually update the semantic search databasezotero_get_search_database_status
: Check database status and configuration
🔍 Search Tools
zotero_search_items
: Search your library by keywordszotero_advanced_search
: Perform complex searches with multiple criteriazotero_get_collections
: List collectionszotero_get_collection_items
: Get items in a collectionzotero_get_tags
: List all tagszotero_get_recent
: Get recently added itemszotero_search_by_tag
: Search your library using custom tag filters
📚 Content Tools
zotero_get_item_metadata
: Get detailed metadata (supports BibTeX export viaformat="bibtex"
)zotero_get_item_fulltext
: Get full text contentzotero_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 libraryzotero_search_notes
: Search in notes and annotations (including PDF-extracted)zotero_create_note
: Create a new note for an item (beta feature)
🔍 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 Claude Desktop config - 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 withzotero-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
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
Connects your Zotero research library with Claude and other AI assistants via the Model Context Protocol, allowing you to search your library, access content, discuss papers, get summaries, and analyze citations.
Related MCP Servers
- AsecurityAlicenseAqualityIntegrates local Zotero libraries with Claude's Desktop interface, allowing users to access and manage their library collections via a local API.Last updated -50MIT License
- AsecurityAlicenseAqualityThis server allows users to interact with their Zotero library through the Model Context Protocol, providing tools for searching items, retrieving metadata, and accessing full text using natural language queries.Last updated -3109MIT License
- -securityAlicense-qualityA server that enables MCP clients like Anthropic Claude App to interact with local Zotero libraries, allowing users to search papers, manage notes, and access research materials through natural language.Last updated -20Apache 2.0
- AsecurityFlicenseAqualityA Model Context Protocol server that connects Claude and other AI assistants to your Notion workspace, allowing AIs to interact with databases, pages, and blocks.Last updated -12011