# Zotero MCP Lite

[![PyPI](https://img.shields.io/pypi/v/zotero-mcp-lite?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/zotero-mcp-lite/)
[![Zotero 7](https://img.shields.io/badge/Zotero-7-CC2936?logo=zotero&logoColor=white)](https://www.zotero.org/)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-Compatible-5A67D8?logo=anthropic&logoColor=white)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![uv](https://img.shields.io/badge/uv-Fast_Package_Manager-DE5FE9?logo=astral&logoColor=white)](https://docs.astral.sh/uv/)

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
```

<details>
<summary>Alternative: Install from GitHub or source</summary>

```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
```

</details>

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

1. Download `cloudflared` if it isn't already on your system (cached under your user data dir).
2. Generate a random admin password and write it to `.env` (or reuse the existing one).
3. Start a Cloudflare tunnel and capture the public `*.trycloudflare.com` URL.
4. Start the MCP server with OAuth enabled.
5. 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.
6. 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 `.env` file is sensitive — keep its file
  permissions tight, do not commit it.
- `--no-auth` exists 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
  (including `zotero_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 filtering
- `zotero_get_recent` - Recently modified/added items (excludes notes by default)
- `zotero_get_collections` - List all collections
- `zotero_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, tags
- `zotero_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](#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](https://github.com/54yyyu) for the original [zotero-mcp](https://github.com/54yyyu/zotero-mcp) project.

## License

MIT License - See [LICENSE](LICENSE) file.