mcp-zotero
Provides tools for searching, browsing, and managing Zotero library items, collections, tags, attachments, and saved searches, with optional semantic search via local embeddings.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-zotero search items for 'deep learning' in my Zotero library"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-zotero
MCP server for Zotero — 38 library tools + optional semantic search via local embeddings.
Install
Base (Zotero API tools only)
uv tool install mcp-zoteroWith semantic search
uv tool install "mcp-zotero[rag]"Adds 8 RAG tools for indexing PDFs and searching by meaning. Downloads a ~80MB embedding model on first use.
With OCR for scanned PDFs
uv tool install "mcp-zotero[rag,ocr]"Adds docling-based OCR fallback for PDFs that contain scanned images instead of text.
Related MCP server: Zotero MCP Server
Configuration
Add to your Claude Code MCP settings (.mcp.json or ~/.claude/settings.json):
{
"mcpServers": {
"zotero": {
"command": "mcp-zotero",
"env": {
"ZOTERO_LIBRARY_ID": "YOUR_LIBRARY_ID",
"ZOTERO_LOCAL": "true",
"ZOTERO_LOCAL_KEY": "YOUR_LOCAL_KEY",
"ZOTERO_API_KEY": "YOUR_API_KEY",
"ZOTERO_ATTACHMENTS_DIR": "~/Zotero/storage"
}
}
}
}Environment variables
Variable | Required | Default | Description |
| Yes | — | Your Zotero library ID |
| No |
|
|
| No |
| Use Zotero Local API (requires Zotero app running) |
| For reads | — | Local API key |
| For writes | — | Web API key from zotero.org/settings/keys |
| For RAG | — | Path to Zotero storage directory |
RAG-only variables (when installed with [rag])
Variable | Default | Description |
|
| Where to store index data |
|
| Sentence transformer model |
|
| Target chunk size in tokens |
|
| Overlap between chunks |
|
| Enable docling OCR fallback for scanned PDFs |
Tools
Base tools (38)
Always available. Covers the full Zotero API:
Search & browse: search_items, top_items, get_item, trash_items, deleted_items
Collections: list_collections, list_collections_top, list_collections_sub, get_collection, collection_items, collection_items_top, collection_tags, create_collections, update_collection, delete_collection, add_item_to_collection, remove_item_from_collection
Tags: list_tags, item_tags, delete_tags
Items: add_item, update_item, delete_item
Attachments: download_attachments, attach_file, attach_linked_file
Schema: item_types, item_fields, item_type_fields, creator_fields, item_creator_types, item_attachment_link_modes
Saved searches: list_searches, list_groups, create_saved_search, delete_saved_search
System: ping, health_check
RAG tools (8)
Available when installed with [rag]. Semantic search across your PDF library:
Tool | Description |
| Index a collection or entire library |
| Index specific items by key |
| Remove items from the index |
| Search passages by meaning |
| Get surrounding text for a search result |
| Find similar passages across documents |
| Get index statistics |
| List all indexed items |
Development
git clone https://github.com/nealcaren/mcp-zotero.git
cd mcp-zotero
uv venv && uv pip install -e ".[dev,rag]"
pytestLicense
MIT
Available Tools
38 toolsadd_itemB
Add an item to Zotero. Optionally attach files (best-effort).
Inputs: req (required). Returns: result
add_item_to_collectionC
Add an item to a collection.
Inputs: req (required). Returns: result
attach_fileC
Attach a local file to an existing item (best-effort).
Inputs: req (required). Returns: result
attach_linked_fileC
Attach a linked (non-uploaded) local file to an existing item.
Inputs: req (required). Returns: result
collection_itemsC
Retrieve items in a collection.
Inputs: req (required). Returns: result
collection_items_topB
Retrieve top-level items in a collection.
Inputs: req (required). Returns: result
collection_tagsB
Retrieve tags for a collection.
Inputs: req (required). Returns: result
create_collectionsD
Create collections.
Inputs: req (required). Returns: result
create_saved_searchC
Create a saved search.
Inputs: req (required). Returns: result
creator_fieldsC
Retrieve creator fields.
Inputs: no named parameters. Returns: result
delete_collectionC
Delete a collection.
Inputs: req (required). Returns: result
deleted_itemsC
Retrieve deleted items (requires since).
Inputs: req (required). Returns: result
delete_itemB
Delete an item.
Inputs: req (required). Returns: result
delete_saved_searchC
Delete saved searches by key.
Inputs: req (required). Returns: result
delete_tagsD
Delete tags.
Inputs: req (required). Returns: result
download_attachmentsC
Download all file attachments for an item to a local directory.
Inputs: req (required). Returns: result
get_collectionC
Retrieve a collection.
Inputs: req (required). Returns: result
get_itemC
Retrieve a single item and (optionally) its children.
Inputs: req (required). Returns: result
health_checkA
Validate configuration without making API calls.
Inputs: no named parameters. Returns: result
item_attachment_link_modesB
Retrieve attachment link mode types.
Inputs: no named parameters. Returns: result
item_creator_typesC
Retrieve creator types for an item type.
Inputs: req (required). Returns: result
item_fieldsB
Retrieve item fields.
Inputs: no named parameters. Returns: result
item_tagsB
Retrieve tags for a specific item.
Inputs: req (required). Returns: result
item_type_fieldsC
Retrieve fields for an item type.
Inputs: req (required). Returns: result
item_typesB
Retrieve item types.
Inputs: no named parameters. Returns: result
list_collectionsC
Retrieve collections.
Inputs: req (required). Returns: result
list_collections_subB
Retrieve subcollections for a collection.
Inputs: req (required). Returns: result
list_collections_topC
Retrieve top-level collections.
Inputs: req (required). Returns: result
list_groupsC
Retrieve user groups.
Inputs: req (required). Returns: result
list_searchesC
Retrieve saved searches.
Inputs: req (required). Returns: result
list_tagsC
Retrieve tags.
Inputs: req (required). Returns: result
pingA
Basic liveness check.
Inputs: no named parameters. Returns: result
remove_item_from_collectionC
Remove an item from a collection.
Inputs: req (required). Returns: result
search_itemsC
Search items by free-text query.
Inputs: req (required). Returns: result
top_itemsC
Retrieve top-level items.
Inputs: req (required). Returns: result
trash_itemsC
Retrieve items in the trash.
Inputs: req (required). Returns: result
update_collectionC
Update a collection's name or parent.
Inputs: req (required). Returns: result
update_itemC
Modify fields on an existing item.
Inputs: req (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 38 tools
Each tool has a clear, distinct purpose. Operations for items, collections, tags, and saved searches are all separated, with no overlapping functionality.
All tool names follow a consistent verb_noun pattern in snake_case, such as add_item, list_collections, delete_tag, etc. No mixing of conventions.
38 tools is on the higher side but justified by the breadth of Zotero's API. Each tool serves a specific function, so the count, while large, is not excessive for a full-featured reference manager integration.
The tool set covers nearly all essential operations: full CRUD for items and collections, tag management, file attachments, saved searches, and metadata queries. No obvious gaps in core reference management workflows.
Related MCP Connectors
Zotero MCP server for Claude and ChatGPT: search, citations, safe writes, PDF passages and pages.
Academic literature search, retrieval, and private library management on top of OpenAlex.
Search arXiv/Semantic Scholar/OpenAlex + medical evidence (PubMed/Europe PMC) + LaTeX/PDF tools.
Federated search of books and papers, BibTeX/RIS citations, open-access retrieval and reading.
Related MCP Servers
- AlicenseBqualityDmaintenanceAllows AI to interact with your Zotero library.5110 npm163MIT
- AlicenseNot gradedqualityDmaintenanceEnables semantic search and management of Zotero reference libraries using PostgreSQL with pg-vector and OpenAI/Ollama embeddings. Provides AI-powered search, full-text extraction, metadata access, annotations, notes, tags, and collections management.3MIT
- AlicenseBqualityDmaintenanceEnables AI assistants to search, cite, and manage research references directly from a Zotero library.99MIT
- AlicenseAqualityDmaintenanceEnables LLM-powered tools to interact with Zotero academic libraries, including searching papers, adding arXiv papers, updating metadata, and generating literature reviews.101MIT