# Zotero Mcp > 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. - **Type:** MCP server - **Install:** `agentstack add mcp-54yyyu-zotero-mcp` - **Verified:** Yes β€” security-reviewed for prompt injection and unsafe behavior - **Seller:** [54yyyu](https://agentstack.voostack.com/s/54yyyu) - **Installs:** 0 - **Category:** [Search](https://agentstack.voostack.com/c/search) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [54yyyu](https://github.com/54yyyu) - **Source:** https://github.com/54yyyu/zotero-mcp - **Website:** https://stevenyuyy.com/zotero-mcp/ ## Install ```sh agentstack add mcp-54yyyu-zotero-mcp ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Zotero MCP: Chat with your Research Libraryβ€”Local or Webβ€”in Claude, ChatGPT, and more. **Zotero MCP** seamlessly connects your [Zotero](https://www.zotero.org/) research library with [ChatGPT](https://openai.com), [Claude](https://www.anthropic.com/claude), and other AI assistants (e.g., [Cherry Studio](https://cherry-ai.com/), [Chorus](https://chorus.sh), [Cursor](https://www.cursor.com/)) via the [Model Context Protocol](https://modelcontextprotocol.io/introduction). Review papers, get summaries, analyze citations, extract PDF annotations, and more! --- ## ✨ Features ### 🧠 AI-Powered Semantic Search - **Vector-based similarity search** over your entire research library (requires `[semantic]` extra) - **Multiple embedding models**: Default (free, local), OpenAI, Gemini, and Ollama - **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 - Semantic search for conceptual and topic-based discovery ### πŸ“š Access Your Content - Retrieve detailed metadata for any item (markdown or BibTeX export) - Get full text content (when available) - Look up items by BetterBibTeX citation key ### πŸ“ Work with Annotations - Extract and search PDF annotations with page numbers - Access Zotero's native annotations - Create and update notes and annotations - Extract PDF table of contents / outlines (requires `[pdf]` extra) ### ✏️ Write Operations - **Add papers by DOI** with auto-fetched metadata and open-access PDF cascade (Unpaywall, arXiv, Semantic Scholar, PMC) - **Add papers by URL** (arXiv, DOI links, generic webpages) or from local files - Create and manage collections, update item metadata, batch-update tags - Find and merge duplicate items with dry-run preview - **Hybrid mode**: local reads + web API writes for local-mode users ### πŸ“Š 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](https://github.com/scitedotai/scite-zotero-plugin) - **Retraction alerts**: Scan your library for retracted or corrected papers - No Scite account required β€” uses public API endpoints ### 🌐 Flexible Access Methods - Local mode for offline access (no API key needed) - Web API for cloud library access - Hybrid mode: read from local Zotero, write via web API ### ⌨️ 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 ## πŸš€ Quick Install > **New to the command line?** Try the community-built [Zotero MCP Setup](https://github.com/ehawkin/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) ```bash uv tool install zotero-mcp-server zotero-mcp setup # Auto-configure (Claude Desktop supported) ``` #### Installing via pip ```bash pip install zotero-mcp-server zotero-mcp setup # Auto-configure (Claude Desktop supported) ``` #### Installing via pipx ```bash pipx install zotero-mcp-server zotero-mcp setup # Auto-configure (Claude Desktop supported) ``` ### Optional Extras Heavy ML/PDF dependencies are separated into optional extras so the base install stays fast and small: | Extra | What it adds | Install command | |-------|-------------|-----------------| | `semantic` | Semantic search via ChromaDB, sentence-transformers, OpenAI/Gemini embeddings | `pip install "zotero-mcp-server[semantic]"` | | `pdf` | PDF outline extraction (PyMuPDF) and EPUB annotation support | `pip install "zotero-mcp-server[pdf]"` | | `scite` | [Scite](https://scite.ai) citation intelligence β€” tallies and retraction alerts (no account needed) | `pip install "zotero-mcp-server[scite]"` | | `all` | Everything above | `pip install "zotero-mcp-server[all]"` | For example, with uv: ```bash 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 # Check for updates zotero-mcp update --check-only # Update to latest version (preserves all configurations) zotero-mcp update ``` ## 🧠 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: ```bash # 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`) - **Ollama**: Runs locally via Ollama API (requires model name, e.g., 'qwen3-embedding') **Using Ollama embeddings:** Install and start Ollama, then pull an embedding model before running `zotero-mcp update-db`: ```bash ollama serve # Small model: fast and lightweight ollama pull nomic-embed-text # Medium model: better multilingual retrieval quality ollama pull bge-m3 ``` When prompted by `zotero-mcp setup --semantic-config-only`, choose **Ollama** and use either `nomic-embed-text` or `bge-m3` as the model name. If you change embedding models later, rebuild the index: ```bash zotero-mcp update-db --force-rebuild ``` When you choose OpenAI, setup also asks whether database updates should use OpenAI Batch API. Batch updates are cheaper for large libraries, but they are asynchronous: submit the batch, wait for completion, then import the embeddings. **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: ```bash # Build the semantic search database (fast, metadata-only) zotero-mcp update-db # Submit OpenAI embeddings through Batch API for this update zotero-mcp update-db --openai-batch # Check and import completed OpenAI Batch API embeddings zotero-mcp openai-batch-status zotero-mcp openai-batch-import # Force realtime OpenAI embeddings even if Batch API is enabled in config zotero-mcp update-db --no-openai-batch # 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 conflicts or changed models, force a rebuild zotero-mcp update-db --force-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 Full documentation is available at [Zotero MCP docs](https://stevenyuyy.com/zotero-mcp/). **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](./docs/getting-started.md).** ### For Claude Desktop (example MCP client) #### Configuration After installation, either: 1. **Auto-configure** (recommended): ```bash zotero-mcp setup ``` 2. **Manual configuration**: Add to your `claude_desktop_config.json`: ```json { "mcpServers": { "zotero": { "command": "zotero-mcp", "env": { "ZOTERO_LOCAL": "true", "ZOTERO_API_KEY": "YOUR_API_KEY", "ZOTERO_LIBRARY_ID": "YOUR_LIBRARY_ID" } } } } ``` For **local read-only use**, `ZOTERO_LOCAL: "true"` is all you need β€” drop the `ZOTERO_API_KEY` and `ZOTERO_LIBRARY_ID` lines entirely. Add them only to enable **write mode**: the local API is fast but read-only, so the server uses the Zotero web API for write operations. - Generate an API key from . - `ZOTERO_LIBRARY_ID` is your numeric **userID**, shown on that same page (for a group library, use the group's ID and also set `ZOTERO_LIBRARY_TYPE: "group"`). > **Tip:** if Claude Desktop reports it can't find the `zotero-mcp` command, use the > absolute path instead (run `zotero-mcp setup-info` or `which zotero-mcp` to find it) β€” > GUI apps don't always inherit your shell `PATH`. #### 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)* ### For Cherry Studio #### Configuration Go to Settings -> MCP Servers -> Edit MCP Configuration, and add the following: ```json { "mcpServers": { "zotero": { "name": "zotero", "type": "stdio", "isActive": true, "command": "zotero-mcp", "args": [], "env": { "ZOTERO_LOCAL": "true" } } } } ``` 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): ```bash zotero-mcp setup --no-local --api-key YOUR_API_KEY --library-id YOUR_LIBRARY_ID ``` ### 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, ollama) - `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) - OpenAI Batch API indexing is configured by `zotero-mcp setup` and can be overridden with `zotero-mcp update-db --openai-batch` or `--no-openai-batch` - `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) - `OLLAMA_EMBEDDING_MODEL`: Ollama embedding model name (qwen3-embedding by default) - `OLLAMA_BASE_URL`: Ollama server URL (default: http://localhost:11434) - `ZOTERO_DB_PATH`: Custom `zotero.sqlite` path (optional) ### Command-Line Options ```bash # 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 --openai-batch # Submit OpenAI embeddings through Batch API zotero-mcp update-db --no-openai-batch # Force realtime OpenAI embeddings for this run zotero-mcp openai-batch-status # Check latest OpenAI embedding batch status zotero-mcp openai-batch-import # Import completed OpenAI batch embeddings 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 ``` ## ⌨️ 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 # Search zotero-cli search "machine learning" # keyword search zotero-cli s "neural networks" --limit 5 # short alias, limit results zotero-cli search --mode semantic "attention mechanisms" zotero-cli search --mode tag "important,reviewed" # Get item details zotero-cli get metadata ABC123 # markdown metadata zotero-cli g metadata ABC123 --format bibtex # BibTeX export zotero-cli get fulltext ABC123 # full text zotero-cli get children ABC123 # attachments and notes # Edit item metadata zotero-cli edit ABC123 --title "New Title" zotero-cli edit ABC123 --add-tags "reviewed,important" --date "2024" # Notes and ann … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source β€” we do not rehost the code. - **Author:** [54yyyu](https://github.com/54yyyu) - **Source:** [54yyyu/zotero-mcp](https://github.com/54yyyu/zotero-mcp) - **License:** MIT - **Homepage:** https://stevenyuyy.com/zotero-mcp/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** β€” Free ## Security capabilities Automated source analysis of v0.1.0 β€” what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source β€” more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** β€” security scan: passed β€” Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-54yyyu-zotero-mcp - Seller: https://agentstack.voostack.com/s/54yyyu - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack β€” the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.