Skip to main content
Glama
zotero-mcp-lite
by xmruuu

Zotero MCP Lite

PyPI Zotero 7 Python 3.10+ MCP License: MIT 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

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

Related MCP server: Zotero MCP

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:

uv tool install zotero-mcp-lite

Alternative (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 serve

Step 2: Setup

zotero-mcp setup

This 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 serve

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

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:

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.

Debugging

Debugging MCP servers can be challenging. Use MCP Inspector:

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.

Available Tools

9 tools
zotero_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

    A3.9/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct operation: navigating collections, retrieving items, metadata, full text, annotations, notes, searching, and recent items. No overlap in functionality.

    Naming Consistency5/5

    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).

    Tool Count5/5

    9 tools is well-scoped for a reference management server. It covers browsing, searching, metadata, full text, annotations, and note creation without being excessive.

    Completeness3/5

    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

    Related MCP Servers