zotero-mcp-lite
Provides tools for searching, reading, and managing Zotero library items, collections, annotations, and notes.
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., "@zotero-mcp-lite Search my Zotero for papers on climate change"
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.
Zotero MCP Lite
A high-performance Model Context Protocol (MCP) server for Zotero with customizable research workflows.
Full Local - No cloud, no API key; runs entirely via Zotero Desktop
Atomic Tools - 9 composable tools; LLM orchestrates as needed
MCP-Native - Works with any MCP client
Extensible - User-editable prompts to match your research style
Easy Deploy - Single command install, auto-detects Zotero
Architecture
flowchart LR
subgraph MCP [Zotero MCP Lite]
Read[Read Operations]
Write[Write Operations]
end
subgraph Zotero [Zotero Desktop]
LocalAPI["/api/ endpoint"]
ConnectorAPI["/connector/ endpoint"]
SQLite[(zotero.sqlite)]
end
Read -->|GET| LocalAPI
Read -->|Direct SQL| SQLite
Write -->|POST saveItems| ConnectorAPI
LocalAPI --> SQLite
ConnectorAPI --> SQLiteRelated MCP server: Zotero MCP
Quick Start
Prerequisites
Python 3.10+
Zotero 7+ installed (the Local API is a Zotero 7 feature; earlier versions are not supported)
Step 0: Enable Zotero Local API
The Local API allows third-party applications to communicate with Zotero. This is required.
Steps:
Open Zotero → Edit → Settings (or Preferences on macOS)
Go to Advanced tab
Under General (in Zotero 7), check "Allow other applications on this computer to communicate with Zotero"
The API will be available at
http://localhost:23119/api/
Note: The Local API requires manual enabling (unlike the browser Connector).
Step 1: Install
Recommended:
uv tool install zotero-mcp-liteAlternative (requires Python 3.10+):
pip install zotero-mcp-lite# From GitHub (latest development version)
uv tool install "git+https://github.com/xmruuu/zotero-mcp-lite.git"
# From source (for development)
git clone https://github.com/xmruuu/zotero-mcp-lite.git
cd zotero-mcp-lite && uv sync
uv run zotero-mcp setup
# Direct run without install
uvx zotero-mcp-lite serveStep 2: Setup
zotero-mcp setupThis detects your Zotero installation and configures MCP clients automatically.
Step 3: Connect to MCP Client
Claude Code (one command):
claude mcp add zotero -- zotero-mcp serveOther MCP clients — add to your MCP config file:
{
"mcpServers": {
"zotero": {
"command": "zotero-mcp",
"args": ["serve"]
}
}
}Config file locations:
claude_desktop_config.json(Claude Desktop), Settings → MCP (Cursor),~/.gemini/settings.json(Gemini CLI)
That's it! You're ready to use Zotero with AI assistants.
Remote setup (claude.ai web · Word add-in · mobile)
The default serve command uses stdio transport, which works only with locally-installed
clients (Claude Desktop, Cursor, Claude Code). To make Zotero MCP available in claude.ai
web, the Microsoft Word Claude add-in, or any other surface that runs through your
claude.ai account, the server must be reachable over HTTPS as a Custom Connector.
Two architectural realities to know up front:
Zotero must run on the same machine as the MCP server — the server talks to Zotero's local API at
127.0.0.1:23119. Each user runs their own server; no central hosted instance is possible.claude.ai Custom Connectors only support OAuth (not pasted bearer tokens). This server embeds a small OAuth 2.1 authorization server with both DCR (RFC 7591) and CIMD support so claude.ai's connector flow works out of the box.
Quickest path: the wizard
zotero-mcp setup --remoteThis will:
Download
cloudflaredif it isn't already on your system (cached under your user data dir).Generate a random admin password and write it to
.env(or reuse the existing one).Start a Cloudflare tunnel and capture the public
*.trycloudflare.comURL.Start the MCP server with OAuth enabled.
Print the connector URL to paste into claude.ai → Settings → Connectors → Add custom connector. When the login page appears in your browser, enter the password from step 2.
Watch for the OAuth handshake to complete and print Connected!
Leave the window open — closing it stops the tunnel and the server. For a long-running deployment, run as a system service.
Manual setup
Prefer to wire things yourself? Set both environment variables in .env:
ZOTERO_MCP_ADMIN_PASSWORD=<a long random string>
ZOTERO_MCP_PUBLIC_URL=https://<your-tunnel-url>Start a tunnel of your choice:
Tunnel | Why |
Cloudflare Tunnel | Free, stable URL, no signup needed for |
ngrok | Easiest for a quick test. Free tier rotates the URL each restart. |
Tailscale Funnel | Free, gives a stable |
Then run the server:
zotero-mcp serve --transport streamable-http --port 8000Add the public URL (with /mcp path) on claude.ai: Settings → Connectors → Add custom
connector.
Security caveats
The admin password is the only thing protecting your Zotero library on the public internet. Use a strong random password. The
.envfile is sensitive — keep its file permissions tight, do not commit it.--no-authexists as an escape hatch for local debugging. Never expose an unauthenticated server through a tunnel — anyone with the URL can read and write your Zotero library (includingzotero_create_note).OAuth tokens persist in a SQLite file under your user data directory. Delete that file to effectively log out claude.ai everywhere.
Features
9 Atomic MCP Tools
Search and Navigation
zotero_search_items- Keyword search with tag filteringzotero_get_recent- Recently modified/added items (excludes notes by default)zotero_get_collections- List all collectionszotero_get_collection_items- Items in a collection (excludes notes by default)zotero_search_annotations- Search highlights across library (PDF, EPUB, snapshot)
Content Reading
zotero_get_item_metadata- Metadata, authors, abstract, tagszotero_get_item_children- Attachments, notes, and annotations (PDF/EPUB/snapshot)zotero_get_item_fulltext- Full text extraction
Writing (via local Connector API)
zotero_create_note- Create note with full formatting support (tables, lists, line breaks)
4 Research Skills (MCP Prompts)
Pre-defined workflows that guide AI through common academic tasks:
Skill | Use Case | What It Does |
| Explore a topic | Searches titles AND your annotations |
| Deep-dive one paper | Structured analysis from annotations or full text |
| Compare papers | Table-rich synthesis with insights |
| Prepare citations | APA, IEEE, and BibTeX formats |
Works with or without annotations. Fully customizable. See Customizing Skills.
Debugging
Debugging MCP servers can be challenging. Use MCP Inspector:
npx @modelcontextprotocol/inspector zotero-mcp serveThis opens a web UI to test tools and prompts interactively.
Technical Notes
Annotations: Direct SQLite query (faster than Web API, works offline)
Cross-platform: Auto-detects Zotero on Windows, macOS, Linux
Architecture: Read via
/api/, Write via/connector/, Annotations via SQLite
Customizing Skills
Prompts are fully customizable. Copy from the package defaults and edit:
~/.zotero-mcp/prompts/
├── literature_review.md # Single paper analysis skill
├── comparative_review.md # Multi-paper comparison skill
├── knowledge_discovery.md # Topic exploration skill
└── bibliography_export.md # Citation export skillLoading order: User files (~/.zotero-mcp/prompts/) take priority over package defaults.
Edit the .md files to customize analysis sections, add new ones, or change the output format entirely.
Credits
Thanks to @54yyyu for the original zotero-mcp project.
License
MIT License - See LICENSE file.
Available Tools
9 toolszotero_create_noteA
Create a note in Zotero with full formatting support (tables, lists, line breaks). Use for: saving literature reviews, summaries, research memos, or any content. Attach to a paper with parent_key for organized reference management. Content is auto-converted to HTML; line breaks and spacing are preserved.
Inputs: content (required), parent_key, tags. Returns: result
zotero_get_collection_itemsA
List all papers and references in a specific collection/folder. Default shows papers only; use item_type='' to include notes in the collection. Returns item keys for get_item_metadata (citation) or get_item_children (highlights).
Inputs: collection_key (required), limit, item_type. Returns: result
zotero_get_collectionsA
List all folders/collections in your reference library with hierarchy. Shows how your literature is organized (by project, topic, course, etc). Use collection key with get_collection_items to browse papers in a folder.
Inputs: limit. Returns: result
zotero_get_item_childrenB
Retrieve your reading annotations and notes for a paper. Returns: highlights (with colors) from PDFs, EPUBs, and webpage snapshots, plus margin comments and standalone notes. Essential for literature_review prompt to analyze your reading insights.
Inputs: item_key (required). Returns: result
zotero_get_item_fulltextA
Extract and read the full text content from a PDF paper. Use when you need to analyze the actual paper content beyond the abstract. Long papers are truncated; ask about specific sections if needed.
Inputs: item_key (required), max_chars. Returns: result
zotero_get_item_metadataA
Get complete bibliographic metadata for academic citation and analysis. Returns: title, authors, abstract, journal/venue, DOI, publication date, and tags. For reading annotations (PDF/EPUB/snapshot) use get_item_children; for full text use get_item_fulltext. TIP: For structured literature review, invoke /literature_review prompt instead of ad-hoc analysis.
Inputs: item_key (required), include_bibtex. Returns: result
zotero_get_recentA
Get recently read, modified, or imported papers from your library. Default shows papers only; use item_type='' to include standalone notes. Use sort_by='dateAdded' for new imports, 'dateModified' for recent reading activity.
Inputs: limit, sort_by, item_type. Returns: result
zotero_search_annotationsA
Search all annotations (PDF, EPUB, snapshot) and your comments across your entire library by keyword. Finds your reading insights containing the search term across all papers. Returns: highlighted text, your comments, page numbers, and parent paper context. Use for: cross-paper knowledge synthesis, finding where you discussed a concept, building thematic connections from your reading history.
Inputs: query (required), limit. Returns: result
zotero_search_itemsA
Search your reference library for papers, articles, books, or notes by keyword. Default searches title/author/year; use qmode='everything' to search full text and note contents. Returns item keys for get_item_metadata (details) or get_item_children (highlights/notes).
Inputs: query (required), qmode, item_type, limit, +1 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool targets a distinct operation: navigating collections, retrieving items, metadata, full text, annotations, notes, searching, and recent items. No overlap in functionality.
All tools follow a consistent 'zotero_verb_noun' pattern with underscores. Verbs clearly indicate action (create, get, search) and nouns specify target (collection, item, note, annotation).
9 tools is well-scoped for a reference management server. It covers browsing, searching, metadata, full text, annotations, and note creation without being excessive.
Covers reading and note creation well but lacks update/delete operations for items and collections. This is acceptable for a 'lite' server, but full lifecycle is incomplete.
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.
Research paper search with real citations and reference formatting for AI assistants
Search arXiv/Semantic Scholar/OpenAlex + medical evidence (PubMed/Europe PMC) + LaTeX/PDF tools.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to search, cite, and manage research references directly from a Zotero library.99MIT
- AlicenseAqualityBmaintenanceEnables AI assistants to search, access, and interact with your Zotero research library, including semantic search, metadata retrieval, PDF annotations, and library management.41MIT
- AlicenseAqualityCmaintenanceEnables AI assistants to read, search, and fully manage a Zotero library locally—organizing collections, editing items, uploading files, and managing notes, tags, and trash—through the local Zotero API without cloud sync.331MIT
- AlicenseAqualityCmaintenanceEnables AI assistants to search, browse, and cite a local Zotero 7 library with zero configuration and no API key, keeping all data on the user's machine.8MIT