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```mermaid
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 --> SQLite
## Quick Start
### Prerequisites
1. **Python 3.10+**
2. **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:**
1. Open **Zotero** → **Edit** → **Settings** (or **Preferences** on macOS)
2. Go to **Advanced** tab
3. Under **General** (in Zotero 7), check **"Allow other applications on this computer to communicate with Zotero"**
4. 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:**```bash
uv tool install zotero-mcp-lite
Alternative (requires Python 3.10+):```bash
pip install zotero-mcp-lite
Alternative: Install from GitHub or source```bash
# 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 serve
Step 2: Setup```bash
zotero-mcp setup
This detects your Zotero installation and configures MCP clients automatically.
### Step 3: Connect to MCP Client
**Claude Code** (one command):```bash
claude mcp add zotero -- zotero-mcp serve
Other MCP clients — add to your MCP config file:```json
{
"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```bash
zotero-mcp setup --remote
This 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:```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 `*.trycloudflare.com`. `cloudflared tunnel --url http://localhost:8000` |
| **ngrok** | Easiest for a quick test. Free tier rotates the URL each restart. `ngrok http 8000` |
| **Tailscale Funnel** | Free, gives a stable `*.ts.net` HTTPS URL. Requires a Tailscale account. |
Then run the server:```bash
zotero-mcp serve --transport streamable-http --port 8000
Add 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 |
|---|---|---|
knowledge_discovery(query) |
Explore a topic | Searches titles AND your annotations |
literature_review(item_key) |
Deep-dive one paper | Structured analysis from annotations or full text |
comparative_review(item_keys) |
Compare papers | Table-rich synthesis with insights |
bibliography_export(item_keys) |
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:```bash
npx @modelcontextprotocol/inspector zotero-mcp serve
This 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 skill
Loading 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.
