Reference · Zotero MCP

Tool groups

An MCP server sends every tool it offers with every request, so each tool uses up context. Optional tools are grouped, and ZOTERO_MCP_TOOLSETS sets which groups are on. A tool that’s turned off doesn’t exist for that session, so the model can’t call it.

Value	Effect
unset	Default: core tools plus `libraries`, `search-admin`, `pdf-geometry`
`all`	Every tool
`none`	Core tools only
`scite,feeds`	Core plus the named groups
`all,-scite`	Everything except the named groups

Group	Default	Contents
`libraries`	on	List and switch between personal and group libraries
`search-admin`	on	Build and inspect the semantic search index
`pdf-geometry`	on	Page layout and PDF outline
`scite`	off	Scite citation counts and retraction checks
`duplicates`	off	Find and merge duplicate items
`discovery`	off	Citation graph lookup and PDF coverage
`feeds`	off	Zotero RSS feed subscriptions
`relations`	off	Related-item links between items
`chatgpt-connector`	auto	`search` and `fetch` for ChatGPT deep research. On over HTTP, off over stdio.

Claude Desktop / Claude Code env

"env": {
  "ZOTERO_LOCAL": "true",
  "ZOTERO_MCP_TOOLSETS": "scite,duplicates"
}

Search

`zotero_search_items`	Search titles, creators, and years, plus abstracts in “everything” mode. Can search every library at once in local mode.
`zotero_advanced_search`	Search on multiple fields with AND or OR, including date ranges
`zotero_search_by_tag`	Filter by tags, with OR and exclusions
`zotero_search_by_citation_key`	Look up one item by its Better BibTeX citation key
`zotero_semantic_search`	Find papers by meaning, using embeddings. Needs `[semantic]`.
`zotero_get_recent`	List recently added items, optionally from one collection
`zotero_update_search_database`search-admin	Build or refresh the semantic index
`zotero_get_search_database_status`search-admin	Show item count, last update, and embedding model

Read

`zotero_get_item_metadata`	An item’s metadata as `markdown`, `json`, or `bibtex`
`zotero_get_item_fulltext`	Extracted text of the item’s main attachment, and says when the text was cut short
`zotero_read_pdf_pages`	Read specific pages of a PDF as text, with garbled math, figures and tables flagged, or as page images (`format='image'`)
`zotero_get_pdf_outline`pdf-geometry	A PDF’s table of contents, with page numbers
`zotero_get_item_children`	Attachments and notes for one item or many
`zotero_get_attachment_path`	Where an item’s attachment files are on disk (local mode)
`zotero_export_bibliography`	Formatted bibliography or in-text citations, from Zotero’s citation engine

Annotations & notes

`zotero_get_annotations`	Highlights and comments on PDF and EPUB attachments, as text or `json`
`zotero_create_annotation`	Highlight text (`text=`), draw a box over a figure or table (`rect=`), or pin a sticky note (`note=`)
`zotero_update_annotation`	Edit an annotation’s text, comment, color, or tags
`zotero_delete_annotation`	Permanently delete an annotation (Zotero’s reader cannot remove trashed ones)
`zotero_get_page_layout`pdf-geometry	Find figures, tables and equations on a page, with box coordinates to pass to `rect=`
`zotero_get_notes`	List notes, or search note and annotation text with `query`
`zotero_manage_note`	Create, update, or trash a note
`zotero_synthesize_annotations`	Gather highlights, comments, and notes into a per-paper summary

Add & edit

`zotero_add_item`	Add from a DOI, URL, ISBN, BibTeX, CSL JSON, or a local file. It detects which one it was given, and accepts a list of DOIs, URLs, or ISBNs.
`zotero_attach_file`	Attach a local file or PDF URL to an existing item
`zotero_update_item`	Update metadata by passing a `fields` object
`zotero_batch_update`	Add or remove tags and Extra fields on many items in one call
`zotero_set_item_parent`	Set, change, or clear an item’s parent
`zotero_delete_item`	Move an item to the Trash
`zotero_write_capabilities`	Show which way writes can go (local, hybrid, web, or none) and what to do if none
`zotero_authorize_local_writes`	Ask Zotero 10+ for local write permission (opens a dialog in Zotero)

The add tools take collections as keys, names, or parent/child paths, and check them before creating anything. if_exists sets what happens when the item is already in your library: "duplicate" always creates a new one, "file" reuses the existing item, and "skip" leaves it alone. zotero-cli add defaults to file.

Collections & libraries

`zotero_get_collections`	All collections as a tree, with their keys
`zotero_get_collection_items`	Items in a collection, optionally including subcollections
`zotero_search_collections`	Find collections by name
`zotero_create_collection`	Create a collection or subcollection
`zotero_update_collection`	Rename a collection or move it under another parent
`zotero_delete_collection`	Delete a collection. Its items stay in the library.
`zotero_set_item_collections`	Add items to collections, or remove them
`zotero_get_tags`	All tags in the active library
`zotero_list_libraries`libraries	Your personal library, group libraries, and feeds (local mode)
`zotero_switch_library`libraries	Choose which library later tool calls use

Optional groups

`scite_enrich_item`scite	Supporting, contrasting, and mentioning citation counts for one paper, plus editorial notices
`scite_enrich_search`scite	Library search results with Scite counts and notices
`scite_check_retractions`scite	List items with retractions, corrections, or expressions of concern
`zotero_find_duplicates`duplicates	Find duplicates by title and/or DOI
`zotero_merge_duplicates`duplicates	Merge duplicates, with a preview first. `auto=True` merges all same-DOI groups after confirmation.
`zotero_find_related_papers`discovery	Papers a work cites, or that cite it, from OpenAlex
`zotero_library_coverage`discovery	Which items have a PDF and which don’t
`zotero_list_feeds`feeds	RSS feed subscriptions in the Zotero app
`zotero_get_feed_items`feeds	Recent items from one feed
`zotero_get_item_related`relations	Related items for an item
`zotero_add_item_relation`relations	Link two items as related (`dc:relation` or `owl:sameAs`)
`zotero_remove_item_relation`relations	Remove a related-item link
`search`, `fetch`chatgpt-connector	The two tools ChatGPT deep research requires

Environment variables

Connection

`ZOTERO_LOCAL`	`true` to use the Zotero app on this computer
`ZOTERO_API_KEY`	Zotero web API key, for web or hybrid mode
`ZOTERO_LIBRARY_ID`	User or group library ID
`ZOTERO_LIBRARY_TYPE`	`user` (default) or `group`
`ZOTERO_LOCAL_API_KEY`	Local write key (Zotero 10+). Usually set for you by `authorize-local`.
`ZOTERO_LOCAL_SERVER_ID`	Which local Zotero database the key belongs to (found automatically)
`ZOTERO_LOCAL_WRITE`	`auto` (default), or `false` to always write through the web API
`ZOTERO_WEBDAV_URL`, `_USERNAME`, `_PASSWORD`	Download attachments from WebDAV in web mode

Reading and tools

`ZOTERO_BACKEND`	`api` to read through the Zotero API even in local mode. `sqlite` forces SQLite.
`ZOTERO_DB_PATH`	Path to `zotero.sqlite`, if it isn’t found automatically
`ZOTERO_MCP_DB_SNAPSHOT_MIN_INTERVAL`	Minimum seconds between database snapshot refreshes (default `5`)
`ZOTERO_MCP_TOOLSETS`	Which optional tool groups are on (see Tool groups)
`ZOTERO_MCP_SCHEMA_REFRESH`	`0` turns off the weekly refresh of Zotero’s item type list

Semantic search

`ZOTERO_EMBEDDING_MODEL`	`default`, `openai`, `gemini`, or `ollama`
`OPENAI_API_KEY`, `OPENAI_EMBEDDING_MODEL`, `OPENAI_BASE_URL`	OpenAI embeddings, or any OpenAI-compatible API
`GEMINI_API_KEY`, `GEMINI_EMBEDDING_MODEL`, `GEMINI_BASE_URL`	Gemini embeddings
`OLLAMA_EMBEDDING_MODEL`, `OLLAMA_BASE_URL`	Ollama embeddings (default server `http://localhost:11434`)

`zotero-mcp`

Runs the server, configures it, and maintains it.

`serve [--transport stdio\|streamable-http\|sse]`	Run the MCP server. `sse` is deprecated.
`setup`	Interactive setup, and writes the Claude Desktop config
`setup-info`	Print the install path and the config other clients need
`authorize-local [--status\|--revoke\|--print]`	Get or manage the local write key
`install-skill [--target\|--list-targets\|--force]`	Install the `zotero-cli` agent skill
`update-db [--fulltext] [--batch] [--force-rebuild]`	Build or update the semantic index
`db-status`, `db-inspect`	Show index status, or inspect indexed documents
`update [--check-only]`	Update to the latest release
`version`	Print the installed version

`zotero-cli`

Your library from the terminal, with no AI assistant needed. It uses the same config as the server. Add --json to any command for one machine-readable object per call.

# search and read
$ zotero-cli search "machine learning"
$ zotero-cli search --mode semantic "attention mechanisms"
$ zotero-cli get metadata ABC123 --format bibtex
$ zotero-cli outline ABC123
$ zotero-cli read ABC123 --start-page 42 --end-page 55
$ zotero-cli read ABC123 --start-page 44 --format image

# notes and annotations
$ zotero-cli notes create --item-key ABC123 --text "My note" --tags "idea"
$ zotero-cli ann list --item-key ABC123 --format json

# add, organize, export
$ zotero-cli add doi 10.1038/s41586-021-03819-2 -c "Reading List"
$ zotero-cli add bibtex --file refs.bib
$ zotero-cli batch --query "machine learning" --add-tags survey --limit 100
$ zotero-cli export --collection COLL01 --format bibtex

JSON output

Every result has the same wrapper, and it always goes to stdout. On success it holds data. On failure it holds error.message and a stable error.code. Run zotero-cli --json-schema for the full format.

$ zotero-cli --json search "attention" --limit 5 --detail keys_only
{"ok": true, "command": "search", "schema": 1, "data": {"count": 5, "items": [...]}}

The CLI guide has the full command reference.

Tools, settings, and commands