Labsco
54yyyu logo

Zotero MCP

★ 4,100

from 54yyyu

Connect your Zotero research library with AI assistants. Supports local/web API access, PDF annotation extraction, and advanced search.

🔥🔥🔥🔥✓ VerifiedAccount requiredNeeds API keys
#automation#social-media#database#documents#git#security#video-editing#memory

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!

✨ 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

  • 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

🧠 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:

Copy & paste — that's it
# 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:

Copy & paste — that's it
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:

Copy & paste — that's it
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:

Copy & paste — that's it
# 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.

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

Copy & paste — that's it
# 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 annotations
zotero-cli notes list ABC123
zotero-cli notes create --item-key ABC123 --text "My note" --tags "idea"
zotero-cli notes create --item-key ABC123 --text - # read from stdin
zotero-cli ann list ABC123 # annotations (short alias)
zotero-cli ann search "highlight text"

# Add items
zotero-cli add doi 10.1038/s41586-021-03819-2
zotero-cli add url https://arxiv.org/abs/2301.00001
zotero-cli add file --filepath /path/to/paper.pdf --title "Override Title"
zotero-cli add isbn 9780262046305
zotero-cli add bibtex --file refs.bib # or --bibtex '@article{...}'
zotero-cli add bibtex --bibtex - Add `-v` anywhere to see progress messages (e.g., which API calls are made):

zotero-cli -v search "CRISPR"

Copy & paste — that's it

## 📑 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](https://retorque.re/zotero-better-bibtex/installation/) 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.

## 🔗 Managing Related Items

Zotero MCP now supports managing relationships between items in your library. This is useful for linking related papers, tracking versions, or connecting preprints to their published versions.

### View Related Items

zotero_get_item_related(item_key="ABCD1234")

Copy & paste — that's it

### Add a Relation

 Create a bidirectional link between two items:

zotero_add_item_relation( item_key="ABCD1234", related_item_key="EFGH5678", relation_type="dc:relation" # Optional, defaults to "dc:relation" )

Copy & paste — that's it

### Remove a Relation

zotero_remove_item_relation( item_key="ABCD1234", related_item_key="EFGH5678", remove_bidirectional=True # Also remove the reverse relation (default: true) )

Copy & paste — that's it

 **Relation Types:**

 

- `dc:relation` — General related items (default) 

- `owl:sameAs` — Items that are the same work (e.g., preprint and published version)

## 📚 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 `format="markdown"`, `format="json"` for complete raw Zotero metadata, and `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 (beta feature) 

- `zotero_get_page_layout`: Detect figure/table regions on a PDF page (with captions and normalized coordinates) for accurate area annotation placement 

### 📊 Scite Citation Intelligence Tools

 

- `scite_enrich_item`: Get Scite citation tallies and retraction alerts for a paper 

- `scite_enrich_search`: Search your Zotero library with Scite-enriched results (tallies + alerts inline) 

- `scite_check_retractions`: Scan items for retractions and editorial notices 

### 📦 Item & Collection Management Tools

 

- `zotero_add_by_doi`: Add a paper by DOI with automatic metadata and open-access PDF attachment 

- `zotero_add_by_url`: Add a paper by URL (arXiv, DOI URLs, and general webpages) 

- `zotero_add_by_isbn`: Add a book by ISBN (Open Library + Google Books cascade) 

- `zotero_add_by_bibtex`: Add one or more items from BibTeX (inline or .bib file) 

- `zotero_add_by_csl_json`: Add one or more items from CSL JSON (inline or file) 

- `zotero_add_from_file`: Import a local PDF or EPUB file with automatic DOI extraction 

 All add tools take a `collections` parameter accepting collection keys, names, or `parent/child` paths — resolved and validated before the item is created, so unknown or ambiguous specs fail with suggestions instead of producing an unfiled item. They also take `if_exists` (`"duplicate"` — default — always creates; `"file"` reuses an existing item matching the DOI/arXiv ID/ISBN/URL, filing it into missing collections and adding missing tags; `"skip"` leaves a match untouched) and `create_missing_collections` (create unknown collection specs, including path chains, instead of failing). The `zotero-cli add` commands default to `--if-exists file`.

 

- `zotero_create_collection`: Create a new collection (folder/project) in your library 

- `zotero_search_collections`: Search for collections by name to find their keys 

- `zotero_manage_collections`: Add or remove items from collections (accepts keys, names, or `parent/child` paths) 

- `zotero_update_item`: Update metadata for an existing item (title, tags, abstract, date, etc.) 

- `zotero_find_duplicates`: Find duplicate items by title and/or DOI 

- `zotero_merge_duplicates`: Merge duplicate items with dry-run preview; consolidates all child items 

- `zotero_get_pdf_outline`: Extract the table of contents / outline from a PDF attachment 

- `zotero_search_by_citation_key`: Look up items by BetterBibTeX citation key (with Extra field fallback) 

### 🔗 Related Items Tools

 

- `zotero_get_item_related`: Get all related items for a specific Zotero item 

- `zotero_add_item_relation`: Add a related item relationship (creates bidirectional link) 

- `zotero_remove_item_relation`: Remove a related item relationship

## 🧪 Testing

### Unit Tests

uv run pytest tests/ # 294 tests, ~2 seconds

Copy & paste — that's it

### 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.

## ☕ Support

If you find Zotero MCP useful, consider buying me a coffee!

## 📄 License

MIT