Zotero 文献管理与引用生成 MCP 服务

zotero-mcp

MCP server that lets AI assistants search, create, organize, and cite from a Zotero library. Produces Word documents with live Zotero field codes. Checks for retractions, finds duplicates, maps citation graphs, and builds a knowledge graph with paper recommendations.

Quickstart

Add to your MCP client config (Claude Code, Claude Desktop, etc.):

{
  "zotero": {
    "command": "uvx",
    "args": ["zotero-mcp-plus"],
    "env": {
      "ZOTERO_API_KEY": "your-api-key",
      "ZOTERO_USER_ID": "your-user-id"
    }
  }
}

Get your API key and user ID at zotero.org/settings/keys.

OPENALEX_API_KEY is also required for the analysis tools (check_retractions, get_citation_graph, check_published_versions). To enable those plus the knowledge graph and full-text search tools, add the extras and an OpenAlex key:

{
  "zotero": {
    "command": "uvx",
    "args": ["zotero-mcp-plus[graph,fulltext]"],
    "env": {
      "ZOTERO_API_KEY": "your-api-key",
      "ZOTERO_USER_ID": "your-user-id",
      "OPENALEX_API_KEY": "your-openalex-key"
    }
  }
}

Free OpenAlex key at openalex.org/users/me.

Operating modes

All 39 tools work with just API credentials — Zotero desktop does not need to be running. Two diagnostic tools (check_ssl_health, audit_local_keys) require no credentials at all.

When Zotero desktop is running, reads automatically use the faster local API. When it is not, reads fall back to the Web API transparently.

Call server_status to check which modes are available.

Tools

Read tools

Write tools

Citation tools

Analysis tools

Knowledge graph tools

Requires the graph extra (uvx "zotero-mcp-plus[graph]" or pip install "zotero-mcp-plus[graph]") and OPENALEX_API_KEY env var.

Full-text search tools

Requires the fulltext extra (uvx "zotero-mcp-plus[fulltext]" or pip install "zotero-mcp-plus[fulltext]").

Use build_index(type='fulltext') to extract text from library PDFs and build the FTS5 search index.

Entity extraction tools

Two-tool pattern: the MCP server provides abstracts, the calling LLM extracts entities, and stores them back.

Diagnostic tools

These two tools require no API credentials and can be used to debug setup problems.

MCP Prompts

Pre-built multi-tool workflows that guide the AI through common tasks:

Writing with live citations

Both document tools use [@ITEM_KEY] markers in content:

Gastric cancer screening reduces mortality [@ABC123]. Multiple studies
support this finding [@DEF456, @GHI789].

• write_cited_document creates a new .docx from markdown
• insert_citations modifies an existing .docx (preserves formatting, including tables)
• Citations are emitted as Vancouver-style superscript numbers
• A References section with a live Zotero bibliography field is appended

After opening in Word with the Zotero plugin: click Refresh to populate the bibliography and switch citation styles.

Reclaiming Zotero cloud storage quota

attach_pdf writes linked files by default, so it no longer consumes quota. Attachments created before that change are still imported (cloud-stored) and still count against it. zotero-migrate-attachments converts imported_file attachments in place by default: each file is copied or downloaded to local disk, hash-verified, replaced with a linked_file attachment on the same parent item, and the original is trashed.

Always start with the dry run — it is the default, and writes nothing:

zotero-migrate-attachments

Read the plan, then convert a small batch first:

zotero-migrate-attachments --apply --modes imported_file --limit 5

Check that those five items look right in Zotero (the PDF should open, and the attachment icon shows a link), then run the rest:

zotero-migrate-attachments --apply

Trashing is reversible and the quota is not returned until the trash is emptied. The migration records its keys in .zotero-attachment-migration-trash.json under the destination directory before trashing anything. DELETE /items/trash is global, so review the trash, then use the separate purge-only invocation:

zotero-migrate-attachments --apply --empty-trash

That loads the keys persisted by the earlier invocation and refuses to run if the trash holds anything the migration did not put there. If --dest was used for migration, pass the same --dest here. The command never infers ownership from whatever happens to be in the trash.

imported_url snapshots are excluded by default because one Zotero snapshot can contain an HTML file plus companion resources. To opt in, use --modes imported_url; even then, a snapshot is migrated only when it is already downloaded locally and its storage directory contains exactly one regular file. Cloud-only or multi-resource snapshots are skipped rather than flattened and damaged.

Useful flags: --modes imported_file (the default), --modes imported_url (explicit validated-snapshot opt-in), --dest DIR (default <ZOTERO_DATA_DIR>/linked-attachments), --no-trash (create the links now, trash later), --include-local-only (also convert attachments Zotero holds no cloud file for — these free no quota), and --limit N.

The same operations are exposed as MCP tools: plan_attachment_migration, migrate_attachments, inspect_trash.

Back up the linked-attachment directory. Linked files do not sync; after migrating, those bytes exist only on this machine.

Architecture

┌─────────────┐  reads+writes  ┌──────────────────┐
│  MCP client │ ──────────────>│ Zotero Web API   │
│             │                │ api.zotero.org   │
│             │  reads (fast)  ├──────────────────┤
│             │ ─ ─ ─ ─ ─ ─ ─>│ Zotero Desktop   │
│             │    (optional)  │ localhost:23119  │
│             │   resolves     ├──────────────────┤
│             │ ──────────────>│ Translation Srv  │
│             │                │ PubMed/CrossRef  │
│             │   analysis     ├──────────────────┤
│             │ ──────────────>│ OpenAlex         │
│             │                │ CrossRef updates │
│             │  knowledge     ├──────────────────┤
│             │  graph + FTS5  │ SQLite + NetworkX│
│             │                │ (local cache)    │
│             │  related       ├──────────────────┤
│             │  papers        │ Semantic Scholar │
└─────────────┘                └──────────────────┘

Setup

1. Create a Zotero Web API key (required)

1. Go to zotero.org/settings/keys
2. Create a key with write access to your library
3. Copy the API key and note your User ID

2. Enable Zotero's local API (optional, for faster reads)

In Zotero Desktop: Settings > Advanced > General > enable Allow other applications on this computer to communicate with Zotero. This is optional — without it, all reads go through the Web API.

3. Install

Option A — uvx (recommended, no clone needed):

Install uv first if you don't have it: astral.sh/uv (one-line install on macOS/Linux). Then use zotero-mcp-plus for the base install or zotero-mcp-plus[graph,fulltext] for the full feature set (see Quickstart above). Your MCP client runs uvx directly — no separate install step.

Option B — local install:

git clone https://github.com/alisoroushmd/zotero-mcp.git
cd zotero-mcp
pip install -e ".[graph,fulltext]"

Then configure your MCP client to run python -m zotero_mcp.

Developing against a live install (uvx + local source):

If your MCP client runs the server via uvx --from 'zotero-mcp-plus @ file:///path/to/zotero-mcp' (or any file:// reference to this checkout), be aware that uvx builds a wheel once and caches it. Editing the source afterwards silently does nothing — the running server keeps using the cached wheel until either:

• the version in pyproject.toml is bumped (a new version → a new cache entry), or
• the cache is invalidated explicitly: uvx --reinstall --from '…' zotero-mcp for one run, or uv cache clean zotero-mcp-plus to purge it.

Either way, the MCP client must then be fully restarted (not just reconnected) so it launches a fresh server process. If a fix you just made doesn't seem to take effect, this cache is almost always why. For rapid iteration, prefer Option B (pip install -e) — editable installs pick up source edits on every server start with no cache in the way.

4. Set up OpenAlex API key (required for analysis and knowledge graph tools)

OPENALEX_API_KEY is required for: check_retractions, get_citation_graph, check_published_versions, build_index(type='graph'), query_knowledge_graph, query_authors, and export_knowledge_graph. OpenAlex requires a free API key as of Feb 2026:

1. Register at openalex.org/users/me
2. Set OPENALEX_API_KEY in your MCP client config

5. Install knowledge graph support (optional)

With uvx (add to your MCP client config args):

zotero-mcp-plus[graph]

With pip (local install):

pip install "zotero-mcp-plus[graph]"

Adds networkx, numpy, and scipy for build_index(type='graph'), query_knowledge_graph, query_authors, and export_knowledge_graph. find_related_papers works without it (uses Semantic Scholar API directly).

Optionally set SEMANTIC_SCHOLAR_API_KEY for improved rate limits.

6. Install full-text search support (optional)

With uvx (add to your MCP client config args):

zotero-mcp-plus[fulltext]

With pip (local install):

pip install "zotero-mcp-plus[fulltext]"

Adds pypdf for extracting text from PDFs. Used by build_index(type='fulltext') to build a searchable FTS5 index. Without it, search_fulltext and build_index(type='fulltext') return an install prompt.

Environment variables

Troubleshooting

Development

pip install -e ".[dev,graph,fulltext]"
python -m pytest tests/ -v

License

MIT