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

| Mode | What it provides | Requirements | | --- | --- | --- | | Cloud (primary) | All reads, writes, citations, attachments, analysis, fulltext, entities | ZOTERO_API_KEY + ZOTERO_USER_ID env vars | | Local (optional) | Faster reads via Zotero desktop's local API (no rate limits) | Zotero 7 desktop running with local API enabled |

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

| Tool | Description | | ------------------------ | ------------------------------------------------------------------------- | | server_status | Check which modes are available | | search_items | Search library items by keyword | | get_item | Fetch item metadata or BibTeX | | get_collections | List all collections | | get_collection_items | List items in a collection | | get_notes | List child notes on an item | | get_item_attachments | List attachments with availability status | | get_pdf_content | Find best path to a paper's full text (PMCID, local PDF, or web download). Pass extract_text=true for inline text |

Write tools

| Tool | Description | | ------------------------------- | -------------------------------------------------------------------- | | create_item | Create item from DOI, PMID, or URL (with duplicate detection) | | create_item_manual | Create item with manual metadata (with duplicate detection) | | create_note | Attach a note to an item | | create_collection | Create a collection | | batch_organize | Bulk-add tags/collection to items | | add_to_collection | Add item to a collection | | update_item | Patch metadata fields | | attach_pdf | Attach a local or auto-downloaded PDF | | trash_items | Move items to trash (reversible) | | empty_trash | Permanently delete all trashed items | | manage_tags | List, remove, or rename tags library-wide (action="list\|remove\|rename") |

Citation tools

| Tool | Description | | ------------------------ | ------------------------------------------- | | write_cited_document | Create new .docx with live Zotero citations | | insert_citations | Insert citations into existing .docx |

Analysis tools

| Tool | Description | | ---------------------- | ---------------------------------------------------------------------------- | | check_retractions | Check items for retractions, corrections, and errata via CrossRef + OpenAlex | | find_duplicates | Scan library for duplicate items by DOI and title similarity | | get_citation_graph | Get citing/referenced works via OpenAlex with in-library flags | | check_published_versions | Check if preprints have been formally published; reports journal and in-library status |

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.

| Tool | Description | | -------------------------- | --------------------------------------------------------------------------------- | | build_index | Build or update citation graph and/or fulltext index (type="graph\|fulltext\|both") | | query_knowledge_graph | PageRank, clusters, bridge papers, shortest paths, neighborhood, timeline, topic evolution, citation velocity, trending | | find_related_papers | Semantic Scholar recommendations from library seeds (like Connected Papers) | | query_authors | Prolific/influential authors, co-author lookup, ego network, author clusters | | export_knowledge_graph | Interactive HTML visualization (citations, authors, or full view) with D3.js |

Full-text search tools

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

| Tool | Description | | -------------------------- | --------------------------------------------------------------------------------- | | search_fulltext | Search indexed full text with BM25 ranking and highlighted snippets |

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.

| Tool | Description | | -------------------------- | --------------------------------------------------------------------------------- | | get_unextracted_abstracts| Get papers with abstracts not yet entity-extracted | | store_entities | Persist typed entities (biomarker, drug, gene, etc.) extracted by the LLM | | search_entities | Query entity index: by_name, by_type, paper_entities (by DOI), co_occurrence, shared_entities |

Diagnostic tools

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

| Tool | Description | | ------------------- | ------------------------------------------------------------------------------------ | | check_ssl_health | Diagnose Python SSL/TLS config — cert paths, CA count, env-var overrides, live HTTPS probes. Returns HEALTHY/DEGRADED/BROKEN verdict with remediation steps. Use when any tool reports CERTIFICATE_VERIFY_FAILED. | | audit_local_keys | Scan local Zotero SQLite for item/collection keys containing characters (0, 1, O) that the Zotero sync server rejects, halting sync. |

MCP Prompts

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

| Prompt | Description | | --------------------- | ------------------------------------------------------------------------------- | | literature_audit | Check retractions, verify preprint publication status, scan for duplicates | | build_and_explore | Build indexes and explore research landscape (influential papers, clusters, trends) | | add_and_verify | Add a paper, check retractions, attach PDF, find related work | | extract_entities | Extract biomedical entities from unprocessed abstracts and store them |

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.

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.

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

| Variable | Required | Description | | -------------------------- | -------- | ----------- | | ZOTERO_API_KEY | Yes | Zotero Web API key — get at zotero.org/settings/keys | | ZOTERO_USER_ID | Yes | Zotero user/group ID — same page as the API key | | OPENALEX_API_KEY | For analysis/graph tools | Required for check_retractions, get_citation_graph, check_published_versions, and all knowledge-graph tools — free at openalex.org/users/me | | ZOTERO_MCP_EMAIL | No | Your email address. Sent in User-Agent headers to CrossRef/OpenAlex polite pools and required for Unpaywall PDF lookup in attach_pdf. Without it, Unpaywall PDF fetches are skipped. | | SEMANTIC_SCHOLAR_API_KEY | No | Improves rate limits for find_related_papers — free at semanticscholar.org | | ZOTERO_DATA_DIR | No | Override path to Zotero desktop data directory (default: ~/Zotero). Used by audit_local_keys and the local PDF path resolver in get_pdf_content. | | ZOTERO_MCP_GRAPH_DB | No | Override path for the knowledge-graph SQLite database (default: ~/.local/share/zotero-mcp/graph.sqlite or $XDG_DATA_HOME/zotero-mcp/graph.sqlite). | | XDG_DATA_HOME | No | Standard XDG override for the default graph DB location. | | PARENT_WATCHDOG_DISABLE | No | Set to 1 to disable the orphan-process watchdog that kills the server when the parent process (Claude.app, uvx, etc.) exits. |

Troubleshooting

| Problem | Cause | Fix | | ------- | ----- | --- | | Cloud CRUD mode requires ZOTERO_API_KEY | Missing env vars | Set ZOTERO_API_KEY and ZOTERO_USER_ID in your MCP client config | | CERTIFICATE_VERIFY_FAILED on any tool | Python SSL misconfiguration | Run check_ssl_health — it diagnoses the cert bundle and returns remediation steps | | attach_pdf never finds a free PDF | ZOTERO_MCP_EMAIL not set | Unpaywall requires a real email address. Set ZOTERO_MCP_EMAIL in your config. | | Analysis tools fail without obvious error | OPENALEX_API_KEY missing | check_retractions, get_citation_graph, and check_published_versions all require it | | Reads are slow | Zotero desktop not running; reads go through Web API | Start Zotero and enable local API for faster reads (optional) | | Item not found after creation | Zotero sync lag | Items created via Web API appear locally after Zotero syncs (usually seconds) | | Version conflict for item | Item was modified between read and write | Retry the operation; the server uses optimistic locking | | Translation server 503 | translate.zotero.org is intermittent | The server falls back to PubMed and CrossRef automatically | | Orphan server processes accumulate | Parent exits without closing stdin | Normal behavior is auto-handled by the watchdog. Disable with PARENT_WATCHDOG_DISABLE=1 if it conflicts with your setup. |

Development

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

License

MIT