zotero-mcp
Provides related paper recommendations based on library seeds, similar to Connected Papers, via the find_related_papers tool.
Allows AI assistants to search, create, organize, and cite from a Zotero library. Provides tools for reading items, writing items, citation management, analysis (retractions, duplicates, citation graph), knowledge graph, and full-text search.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@zotero-mcp search for recent papers on metacognition"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: zotero-mcp
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.
Mode | What it provides | Requirements |
Cloud (primary) | All reads, writes, citations, attachments, analysis, fulltext, entities |
|
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 |
| Check which modes are available |
| Search library items by keyword |
| Fetch item metadata or BibTeX |
| List all collections |
| List items in a collection |
| List child notes on an item |
| List attachments with availability status |
| Find best path to a paper's full text (PMCID, local PDF, or web download). Pass |
Write tools
Tool | Description |
| Create item from DOI, PMID, or URL (with duplicate detection) |
| Create item with manual metadata (with duplicate detection) |
| Attach a note to an item |
| Create a collection |
| Bulk-add tags/collection to items |
| Add item to a collection |
| Patch metadata fields |
| Attach a local or auto-downloaded PDF |
| Move items to trash (reversible) |
| List trash contents — call before |
| Permanently delete all trashed items (global, irreversible) |
| Dry-run plan for converting cloud attachments to linked files |
| Convert cloud attachments to linked files (dry run unless |
| List, remove, or rename tags library-wide ( |
Citation tools
Tool | Description |
| Create new .docx with live Zotero citations |
| Insert citations into existing .docx |
Analysis tools
Tool | Description |
| Check items for retractions, corrections, and errata via CrossRef + OpenAlex |
| Scan library for duplicate items by DOI and title similarity |
| Get citing/referenced works via OpenAlex with in-library flags |
| 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 or update citation graph and/or fulltext index ( |
| PageRank, clusters, bridge papers, shortest paths, neighborhood, timeline, topic evolution, citation velocity, trending |
| Semantic Scholar recommendations from library seeds (like Connected Papers) |
| Prolific/influential authors, co-author lookup, ego network, author clusters |
| 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 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 papers with abstracts not yet entity-extracted |
| Persist typed entities (biomarker, drug, gene, etc.) extracted by the LLM |
| 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 |
| 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 |
| Scan local Zotero SQLite for item/collection keys containing characters ( |
MCP Prompts
Pre-built multi-tool workflows that guide the AI through common tasks:
Prompt | Description |
| Check retractions, verify preprint publication status, scan for duplicates |
| Build indexes and explore research landscape (influential papers, clusters, trends) |
| Add a paper, check retractions, attach PDF, find related work |
| 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_documentcreates a new .docx from markdowninsert_citationsmodifies 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-attachmentsRead the plan, then convert a small batch first:
zotero-migrate-attachments --apply --modes imported_file --limit 5Check 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 --applyTrashing 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-trashThat 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)
Go to zotero.org/settings/keys
Create a key with write access to your library
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
versioninpyproject.tomlis bumped (a new version → a new cache entry), orthe cache is invalidated explicitly:
uvx --reinstall --from '…' zotero-mcpfor one run, oruv cache clean zotero-mcp-plusto 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:
Register at openalex.org/users/me
Set
OPENALEX_API_KEYin 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 |
| Yes | Zotero Web API key — get at zotero.org/settings/keys |
| Yes | Zotero user/group ID — same page as the API key |
| For analysis/graph tools | Required for |
| No | Your email address. Sent in User-Agent headers to CrossRef/OpenAlex polite pools and required for Unpaywall PDF lookup in |
| No | Improves rate limits for |
| No | Raises the PubMed/eutils rate limit from 3 to 10 req/s — helps bulk identifier resolution and graph builds. Free at ncbi.nlm.nih.gov/account. |
| No | Override path to Zotero desktop data directory (default: |
| No | Where |
| No |
|
| No | Override path for the knowledge-graph SQLite database (default: OS-native per-user data dir — |
| No | Maximum combined persisted graph records loaded into NetworkX (papers, citations, topics, authors, and paper-author links). Defaults to |
| No | Standard XDG override for the default graph DB location. |
| No | Set to |
Troubleshooting
Problem | Cause | Fix |
| Missing env vars | Set |
| Python SSL misconfiguration | Run |
|
| Unpaywall requires a real email address. Set |
Analysis tools fail without obvious error |
|
|
Knowledge graph materialization is refused | The persisted graph exceeds the default 100,000-record in-memory safety ceiling | Reduce/rebuild the graph, or set |
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) |
| 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 |
Development
pip install -e ".[dev,graph,fulltext]"
python -m pytest tests/ -vLicense
MIT
Available Tools
39 toolsadd_to_collectionAIdempotent
Add an existing Zotero item to a collection. Use this to organize a paper into a folder without moving it from other collections.
Inputs: item_key (required), collection_key (required). Returns: result
attach_pdfA
Attach a PDF to a Zotero item. Can auto-download a free PDF via Unpaywall/PMC/bioRxiv, or accept a local file path. Use this when the user wants to add a PDF to a paper that doesn't have one.
Inputs: parent_key (required), doi, pdf_path. Returns: result
audit_local_keysARead-onlyIdempotent
Audit the local Zotero SQLite database for collection/item keys that contain forbidden characters (0, 1, I, O). Such keys are rejected by the Zotero sync server with 'not a valid collection/item key' and halt sync with 'Made no progress during upload -- stopping'. Use this as a diagnostic when the user reports sync errors, or proactively after any bulk library operation. Reads ~/Zotero/zotero.sqlite read-only (override with the ZOTERO_DATA_DIR env var). Returns a summary with the offending keys, their names, and sync state so they can be rekeyed manually before the next sync.
Inputs: include_items. Returns: result
batch_organizeA
Add tags and/or move multiple items to a collection in one operation. Use this for bulk organization — e.g. tagging a set of search results or grouping papers into a collection. Handles rate limiting and version conflicts.
Inputs: item_keys (required), tags, collection_key. Returns: result
build_indexA
Build or update indexes for your Zotero library. Use this after adding new papers to enable graph queries and full-text search. Types: 'graph' (citation network + analytics via OpenAlex — enables query_knowledge_graph, query_authors, export_knowledge_graph), 'fulltext' (PDF text extraction + FTS5 index — enables search_fulltext), 'both' (runs graph then fulltext). Auto-detects full build vs incremental sync. Set full_rebuild=true to force a complete rebuild.
Inputs: type, limit, full_rebuild. Returns: result
check_published_versionsARead-onlyIdempotent
Check if preprints have been formally published in a peer-reviewed journal. Use this when the user has bioRxiv/medRxiv/arXiv papers and wants to know if a final journal version exists. Reports published DOI, journal name, and whether the published version is already in the library. Uses CrossRef and OpenAlex.
Inputs: item_keys (required). Returns: result
check_retractionsARead-onlyIdempotent
Check whether papers have been retracted or corrected. Uses CrossRef (authoritative) and OpenAlex. Use this when the user asks about paper validity, before citing papers, or as part of a literature audit. Accepts one or more item keys.
Inputs: item_keys (required). Returns: result
check_ssl_healthARead-onlyIdempotent
Diagnose Python SSL/TLS certificate configuration. Use when any tool reports CERTIFICATE_VERIFY_FAILED, SSL errors, or HTTPS failures (OpenAlex, CrossRef, PubMed, etc). Returns Python/OpenSSL versions, resolved cert bundle paths, CA count, env-var overrides (flagging any pointing at missing paths), certifi version, live probes against canonical endpoints, a verdict (HEALTHY/DEGRADED/BROKEN), and concrete remediation steps. Safe, read-only. Set probe=False for offline config-only diagnostics.
Inputs: probe. Returns: result
create_collectionA
Create a new collection (folder) in Zotero, optionally nested under a parent. Use this when the user wants to organize papers into a new group.
Inputs: name (required), parent_key. Returns: result
create_itemA
Add a paper to Zotero from any identifier: DOI, PMID, or URL (PubMed, bioRxiv, arXiv, publisher pages). Resolves metadata automatically and checks for duplicates. Use this when the user wants to save a paper to their library. Optional title is only used for bare URLs that can't be scraped. If you only have structured fields (title/authors/etc.) and no DOI/PMID/URL to resolve, use create_item_manual instead. The result includes dedup_check_failed=true if the duplicate check could not be completed.
Inputs: input (required), tags, title, collection_keys. Returns: result
create_item_manualA
Create a Zotero item with manually provided metadata fields. Use this instead of create_item when you have structured metadata already (e.g. from a conversation) rather than a DOI/URL to resolve. Checks for duplicates.
Inputs: title (required), item_type (required), doi, url, +11 more. Returns: result
create_noteA
Create a note attached to a Zotero item. Use this to save reading notes, summaries, or annotations on a paper. Supports HTML or plain text content.
Inputs: content (required), parent_key (required), tags. Returns: result
empty_trashADestructive
Permanently delete ALL items in the Zotero trash. THIS IS IRREVERSIBLE. This is a GLOBAL operation — it destroys everything in the trash, not just items you recently trashed. Call inspect_trash first to see what is in there, and always confirm with the user before calling this tool.
Inputs: no named parameters. Returns: result
export_knowledge_graphARead-onlyIdempotent
Export the knowledge graph as an interactive HTML visualization that opens in any browser. Use this when the user wants to see their citation network visually, explore research clusters, or share a graph. Views: 'citations' (paper nodes + citation edges, colored by cluster), 'authors' (author nodes + co-authorship edges), 'full' (both layers, papers capped at 200 by PageRank). Requires build_index(type='graph') to have been run first.
Inputs: path, view. Returns: result
find_duplicatesARead-onlyIdempotent
Scan the Zotero library for duplicate items using DOI match and title similarity (>85%). Use this when the user wants to clean up their library or after bulk imports. Optionally scoped to a single collection.
Inputs: limit, collection_key. Returns: result
get_citation_graphARead-onlyIdempotent
Get papers that cite or are cited by a Zotero item, via OpenAlex. Use this when the user wants to explore a paper's citation network, find related work, or trace the influence of a paper. Each result is flagged with in_library (true/false). Direction: 'cited_by', 'references', or 'both'.
Inputs: item_key (required), limit, direction. Returns: result
get_collection_itemsARead-onlyIdempotent
List all items in a specific Zotero collection by its key. Use this when the user wants to see what's in a particular folder/collection.
Inputs: collection_key (required), limit, offset, response_format. Returns: result
get_collectionsARead-onlyIdempotent
List all collections (folders) in the Zotero library with their keys, names, parent relationships, and item counts. Use this when the user asks about their library organization or wants to browse/find a collection.
Inputs: response_format. Returns: result
get_itemARead-onlyIdempotent
Get detailed metadata for a single Zotero item by its key. Use this when you need full bibliographic details (title, authors, DOI, abstract, dates) for a specific item. Set format='bibtex' for BibTeX export.
Inputs: item_key (required), format, response_format. Returns: result
get_item_attachmentsARead-onlyIdempotent
List file attachments (PDFs, etc.) on a Zotero item with availability status. Use this to check whether a paper HAS a PDF before fetching it; to actually read the content, use get_pdf_content. Returns {items, count} where each item's availability is one of: stored_remote_available, stored_local_available, linked_local_available, or metadata_only.
Inputs: parent_key (required). Returns: result
get_notesARead-onlyIdempotent
Get all notes attached to a Zotero item. Use this when the user wants to read their annotations, reading notes, or comments on a paper.
Inputs: parent_key (required). Returns: result
get_pdf_contentARead-onlyIdempotent
Get the full text of a paper in the library. Routes to the best available source: PubMed Central, local PDF, web PDF download, or free open-access PDF. Use this when the user wants to read a paper's content; to only CHECK whether a PDF exists without fetching it, use get_item_attachments first. Set extract_text=true to extract and return the text inline; otherwise returns a file path or PMCID for the caller to read. The response always includes a content_source field (one of: pmc, local_pdf, web_pdf, free_pdf_, extracted_text, not_found) that determines which other fields are present.
Inputs: item_key (required), extract_text. Returns: result
get_unextracted_abstractsARead-onlyIdempotent
Get papers that have abstracts but no extracted biomedical entities yet. Use this to find papers needing entity extraction, then extract entities (conditions, drugs, genes, biomarkers, methods, outcomes) from the returned abstracts and save them with store_entities.
Inputs: limit. Returns: result
insert_citationsA
Insert live Zotero citation field codes into an existing Word document. Finds [@ITEM_KEY] markers in the .docx and replaces them with Zotero field codes. Use this to add citations to a document the user already has; to create a NEW .docx from markdown instead, use write_cited_document. Preserves existing formatting, styles, images, and layout.
Inputs: document_path (required), output_path. Returns: result
inspect_trashARead-onlyIdempotent
List everything currently in the Zotero trash, with item type and title. Use this BEFORE empty_trash so the user can see exactly what would be permanently destroyed — empty_trash is global and irreversible.
Inputs: no named parameters. Returns: result
manage_tagsADestructive
Manage tags in your Zotero library. Use this when the user asks about tags, wants to list/filter tags, remove a tag from all items, or rename a tag. Actions: 'list' (browse tags, optional prefix filter), 'remove' (DESTRUCTIVE: deletes the tag from every item in the library, not reversible — requires tag), 'rename' (rewrites the tag on every item library-wide — requires tag and new_tag). Confirm with the user before 'remove' or 'rename'.
Inputs: tag, action, prefix, new_tag. Returns: result
migrate_attachmentsADestructive
Convert Zotero imported (cloud-stored) attachments into linked files: copy or download each file to local disk, hash-verify it, create a linked_file attachment, then move the original to the trash. Frees cloud storage quota while keeping every file locally. DEFAULTS TO A DRY RUN — pass apply=true to make changes, and only after showing the user plan_attachment_migration output. Never empties the trash; use inspect_trash then empty_trash for that, so the user can review what would be permanently destroyed.
Inputs: apply, limit, modes, dest_dir, +2 more. Returns: result
plan_attachment_migrationARead-onlyIdempotent
Plan a migration of Zotero imported (cloud-stored) attachments to linked files, which keeps every PDF on local disk but frees Zotero cloud storage quota. READ-ONLY: inventories the library, reports which attachments would be converted, which must be downloaded from the cloud first, and which are skipped and why. Nothing is written, downloaded, or trashed. Run this before migrate_attachments.
Inputs: limit, modes, dest_dir, response_format, +1 more. Returns: result
query_authorsARead-onlyIdempotent
Query the author co-authorship network in your knowledge graph. Use this when the user asks about who publishes most, who collaborates with whom, or wants to map out an author's network. Query types: 'prolific' (authors by paper count), 'influential' (authors by summed PageRank of their papers), 'coauthors_of' (co-authors of a named author, ranked by shared papers), 'network' (ego network for an author within N hops — requires author_name, optional depth), 'clusters' (author community groupings). Requires build_index(type='graph') to be run first.
Inputs: query_type (required), depth, limit, author_name. Returns: result
query_knowledge_graphARead-onlyIdempotent
Query the knowledge graph for insights about your library's citation network. Use this when the user asks about influential papers, research clusters, publication trends, or relationships between papers. Query types: 'influential' (PageRank-ranked papers), 'clusters' (research topic groupings), 'bridges' (papers connecting different clusters), 'path' (shortest citation path between two DOIs — requires doi_a and doi_b), 'neighborhood' (papers within N hops of a DOI — requires doi and optional depth), 'stats' (graph summary), 'timeline' (papers per month — optional topic filter, start_year, end_year), 'topic_evolution' (per-subfield paper counts by month — optional start_year, end_year), 'citation_velocity' (month-by-month citation count for a DOI — requires doi), 'trending' (papers with accelerating citation rates — optional limit, years window). Requires build_index(type='graph') to be run first.
Inputs: query_type (required), doi, depth, doi_a, +7 more. Returns: result
search_entitiesARead-onlyIdempotent
Search the biomedical entity graph. Use this when the user asks about which papers mention a condition/drug/gene, what entities co-occur, or what two papers have in common. Query types: 'by_name' (papers mentioning an entity), 'by_type' (common entities of a type, or list all types if no type given), 'co_occurrence' (entities that co-occur with a given entity), 'shared_entities' (entities shared by two papers — requires doi_a and doi_b), 'paper_entities' (all entities extracted from a paper — requires doi).
Inputs: query_type (required), doi, doi_a, doi_b, +3 more. Returns: result
search_fulltextARead-onlyIdempotent
Search the full text of indexed PDFs in your library. Use this when the user wants to find papers that mention a specific term, method, drug, or concept in their body text (not just titles/abstracts). Returns matching papers with highlighted text snippets. Requires build_index(type='fulltext') to be run first.
Inputs: query (required), limit. Returns: result
search_itemsARead-onlyIdempotent
Search Zotero library items by keyword. Use this when the user asks to find papers, look up references, or search their library. Supports title, author, and tag matching. Filter by item_type (e.g. 'journalArticle', 'book') or tag (exact tag name).
Inputs: query (required), tag, limit, offset, +2 more. Returns: result
server_statusARead-onlyIdempotent
Check which Zotero MCP operating modes are available and get fix instructions for any that are misconfigured. Use this first when tools return 'unavailable' errors or when starting a new session to verify connectivity.
Inputs: no named parameters. Returns: result
store_entitiesA
Store extracted biomedical entities for papers. Call this after extracting entities from abstracts (via get_unextracted_abstracts or any paper reading). Entity types: condition, biomarker, drug, method, gene, organism, outcome, dataset. Input: list of {doi, entities: [{name, type}]}.
Inputs: results (required). Returns: result
trash_itemsADestructive
Move Zotero items to trash (reversible). Use this when the user wants to delete papers. Accepts one or more item keys. Items can be restored from trash in Zotero. Confirm with user before trashing.
Inputs: item_keys (required). Returns: result
update_itemADestructive
Update metadata fields on an existing Zotero item. Use this to correct titles, authors, dates, DOIs, or other bibliographic fields. Uses optimistic locking to prevent overwriting concurrent changes.
Inputs: fields (required), item_key (required). Returns: result
write_cited_documentA
Create a new Word document from markdown text with live Zotero citations. Use [@ITEM_KEY] markers in the content for citations. Use this when writing a new document from scratch (e.g. literature review, manuscript draft). For adding citations to an existing document, use insert_citations instead.
Inputs: content (required), output_path (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 39 tools
Most tools target a distinct resource+action pair, and potentially confusing clusters are well-differentiated in descriptions (search_items is metadata search, search_fulltext is PDF text, search_entities is the entity graph). A few adjacent pairs — check_retractions vs check_published_versions and get_citation_graph vs find_related_papers vs query_knowledge_graph — occupy overlapping territory and could cause misselection without careful reading.
Nearly all 39 tools follow a consistent verb_noun pattern (get_item, create_collection, trash_items, query_knowledge_graph, export_knowledge_graph), with modifiers like manual and cited_document kept predictable. Two deviations stand out: batch_organize inverts to adverb_verb, and add_to_collection uses a prepositional form rather than a verb_noun structure like add_item_to_collection.
At 39 tools, this is a heavy surface that exceeds the 25+ threshold for comfortable agent navigation. The count is inflated by several niche sub-domains tacked onto core library management — SSL diagnostics, SQLite key auditing, attachment migration planning, and a full biomedical entity extraction pipeline — making the toolset feel bloated even though each individual tool has a defined purpose.
The core item lifecycle is well covered (create, search, get, update, trash, inspect trash, empty trash), and advanced features like citation graphs, full-text search, and retraction checks are solid. Notable gaps remain: notes can be read and created but not updated or deleted, collections cannot be deleted or have items removed from them, duplicates can be found but not merged, and there is no tool to restore trashed items.
Maintenance
Related MCP Connectors
Zotero MCP server for Claude and ChatGPT: search, citations, safe writes, PDF passages and pages.
Remote MCP server for full read/write access to a Zotero library
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Related MCP Servers
- AlicenseCqualityBmaintenanceAn MCP server that lets AI assistants add papers and books to your Zotero library by DOI, arXiv ID, or ISBN, and manage your collections, tags, and items.5162 PyPI2MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that connects AI assistants to your Zotero library, enabling full-text PDF extraction and metadata search.MIT
- AlicenseAqualityAmaintenanceAn MCP server that gives AI assistants complete, safe access to your Zotero library for searching, citing, adding papers, and formatting bibliographies, with local-first privacy.471,746 npm65MIT
- AlicenseNot gradedqualityCmaintenanceAn MCP server that gives AI agents read access to a Zotero library, enabling search, item metadata, collections, tags, notes, and full-text search of attached PDFs.MIT