zotero-api-mcp
Provides tools for interacting with the Zotero API, enabling management of library items, collections, notes, annotations, attachments, and search.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
zotero-api-mcp
A clean, one-to-one MCP server for the Zotero API, just the API.
Features
22 MCP tools covering the full Zotero API surface
Local API support (
ZOTERO_LOCAL=true) — no API key neededWeb API support with interactive setup wizard
Full CRUD: create items by DOI, arXiv, ISBN; update metadata; delete to trash
Collections: create, add/remove items, search
Notes & Annotations: read, create
Attachments: add files or URLs, read metadata
Library management: stats, trash, groups, tags
Secure by default: API key stored with
SecretStr, XML parsing viadefusedxmlConfiguration:
.envfile support withZOTERO_prefix,pydantic-settingsMulti-library support: Query any group or user library per-call without reconfiguring
Related MCP server: mcp-zotero
Multi-Library Support
All tools accept optional library_id and library_type keyword parameters to override the default library configured in your environment. This lets you query multiple Zotero group libraries without restarting the server or changing your .env file.
Example: Query a group library from any tool:
zotero_search_items(query="machine learning", library_id="<group-id>", library_type="group")
zotero_get_item("ABC12345", library_id="<group-id>", library_type="group")
zotero_get_collection_items("XYZ99999", library_id="<group-id>", library_type="group")library_id— The Zotero library ID (user ID or group ID)library_type— Either"user"or"group"Both default to your configured
ZOTERO_LIBRARY_ID/ZOTERO_LIBRARY_TYPEwhen omittedWorks with all 22 tools — search, items, collections, notes, annotations, and attachments
Stateless: each call is independent, no session-level switching needed
Quick Start
# Run directly (auto-installs)
uvx zotero-api-mcp serve
# Or install globally
uv tool install zotero-api-mcp
zotero-api-mcp serveLocal Mode (no API key)
Set the environment variable and run:
ZOTERO_LOCAL=true uvx zotero-api-mcp serveRequires Zotero running with "Allow other applications to access Zotero" enabled in Preferences → Advanced → General.
Web API Mode
zotero-api-mcp setupYou'll need a Zotero API key from https://www.zotero.org/settings/keys and your library ID.
MCP Configuration
VS Code / Cline / Claude Desktop
Local mode (read-only, no API key):
{
"servers": {
"zotero-api": {
"type": "stdio",
"command": "uvx",
"args": ["zotero-api-mcp", "serve"],
"env": {
"ZOTERO_LOCAL": "true"
}
}
}
}Web API mode (full read/write, requires API key):
{
"servers": {
"zotero-api": {
"type": "stdio",
"command": "uvx",
"args": ["zotero-api-mcp", "serve"],
"env": {
"ZOTERO_API_KEY": "<your-api-key>",
"ZOTERO_LIBRARY_ID": "<your-user-id>",
"ZOTERO_LIBRARY_TYPE": "user"
}
}
}
}Get your API key at https://www.zotero.org/settings/keys and find your user ID there too. Set ZOTERO_LIBRARY_TYPE to "group" if your default library is a group.
Tools
Search & Discovery (9 tools)
zotero_search_items— Search by query, type, tag, or collectionzotero_get_item— Full details for a specific itemzotero_get_item_children— Notes and attachments for an itemzotero_search_collections— List/search collectionszotero_get_collection_items— Items in a collectionzotero_search_tags— List/search tagszotero_get_trash— Items in trashzotero_get_library_stats— Library statisticszotero_get_groups— Group libraries
Item Management (5 tools)
zotero_add_by_doi— Add paper by DOI (CrossRef metadata)zotero_add_by_arxiv— Add paper by arXiv IDzotero_add_by_isbn— Add book by ISBN (OpenLibrary metadata)zotero_update_item— Update title, abstract, date, extrazotero_delete_items— Move items to trash
Collections (3 tools)
zotero_create_collection— Create a new collectionzotero_add_to_collection— Add items to a collectionzotero_remove_from_collection— Remove items from a collection
Notes (2 tools)
zotero_add_note— Add a note to an itemzotero_read_note— Read a note's content
Annotations (1 tool)
zotero_read_annotations— Read PDF annotations for an item
Attachments (2 tools)
zotero_add_attachment— Attach a file or URL to an itemzotero_read_attachment— Get attachment metadata
Comparison with other Zotero MCP servers
Feature | zotero-api-mcp | zotero-mcp (kujenga) | zotero-mcp-lite (xmruuu) | zotero-mcp-server (54yyyu) |
Tools | 22 | 3 | 9 | ~30 |
Philosophy | 1:1 API mapping | Minimal | Read-focused | AI-heavy |
CRUD (create/update/delete) | ✅ | ❌ | ❌ | ✅ |
DOI/arXiv/ISBN import | ✅ | ❌ | ❌ | ✅ |
Collection management | ✅ | ❌ | ❌ | ✅ |
Attachment management | ✅ | ❌ | ❌ | ❌ |
Local API (no key) | ✅ | ❌ | ✅ | ❌ |
Semantic search / AI | ❌ | ❌ | ❌ | ✅ |
Dependencies | 6 | 4 | 9 | 97 |
Development
See CONTRIBUTING.md for full setup and guidelines.
# Install dependencies (requires uv)
uv sync --group dev
# Run tests
just test # Quick: current Python
just test-all # Full: Python 3.12–3.14 via tox
# Version management
just version # Show current version
just bump-patch # 0.0.1 → 0.0.2, creates git tag + commitLicense
MIT — see LICENSE for details.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Zotero MCP server for Claude and ChatGPT: search, citations, safe writes, PDF passages and pages.
Remote MCP server for full read/write access to a Zotero library
Search, read and cite documents. Add, replace and delete files with write access. OAuth required.
Turn DOIs, ISBNs, arXiv or PubMed ids into verified references and export them in any style.
Related MCP Servers
- AlicenseBqualityDmaintenanceIntegrates with Zotero's local API to search your reference library, retrieve bibliographic details, and extract full text from PDF attachments.41MIT
- AlicenseCqualityDmaintenanceEnables interaction with Zotero libraries for searching, managing collections, items, tags, and attachments, plus optional semantic search across PDFs via local embeddings.3813 PyPI2MIT
- AlicenseAqualityBmaintenanceEnables read and write access to a Zotero library via its Web API, allowing search, create, update, and delete of items, notes, and collections.121MIT
- AlicenseNot gradedqualityCmaintenanceEnables managing Zotero libraries via the official Web API v3, including searching, creating, editing, and deleting items, collections, tags, notes, attachments, and performing batch operations, syncs, and file uploads/downloads.MIT