MCP Zotero

This project provides read-only MCP access to one Zotero group library. It uses the Zotero Web API v3 and can run over Streamable HTTP or stdio.

The server is stateless. It does not keep a local index. It does not download or parse PDF files. Zotero performs the search and supplies synchronized attachment text.

Tools

search_papers

Search Zotero with qmode=everything. The server resolves attachment, note, and annotation results to their parent bibliographic items. It then removes duplicate papers.

The Zotero Web API currently supports phrase search. For broad discovery, use separate short queries and synonyms. Zotero does not provide a relevance sort for item requests, so results use the most recently modified items first. Zotero's result count is a count of raw matching items, not unique parent papers.

get_paper

Get all metadata and the attachment list for one bibliographic item.

get_paper_text

Get synchronized text from Zotero's /items/{attachmentKey}/fulltext endpoint. The tool does not request the attachment file.

The tool returns a bounded character range by default. Supply query to get excerpts around literal matches. Zotero full text has no reliable page boundaries, so the tool uses character offsets.

Related MCP server: zotero-mcp

Requirements

• Python 3.13 or later

• Zotero group ID (find from the URL)

• A read-only Zotero API key with access to the group and its files

Create a dedicated key in your Zotero account settings. The MCP endpoint has no authentication and must stay on a private network.

Configuration

Copy the example configuration:

cp .env.example .env

Set these required values:

ZOTERO_GROUP_ID=123456
ZOTERO_API_KEY=replace-with-a-read-only-api-key

The main optional settings are:

MCP_TRANSPORT=streamable-http  # or stdio
MCP_HOST=127.0.0.1
MCP_PORT=8000
MCP_LOG_LEVEL=INFO
MCP_MAX_TEXT_CHARACTERS=12000
ZOTERO_TIMEOUT_SECONDS=30
ZOTERO_MAX_RETRIES=3
ZOTERO_MAX_SEARCH_PAGES=20

Install and run

Install the project with uv:

uv sync

Start the server. The default is Streamable HTTP:

uv run mcp-zotero

Set MCP_TRANSPORT=stdio in .env to run over standard input/output instead:

MCP_TRANSPORT=stdio uv run mcp-zotero

Streamable HTTP

The MCP endpoint is:

http://127.0.0.1:8000/mcp

Point the LiteLLM MCP server configuration at this URL. No MCP authorization header is required. Use MCP_HOST=0.0.0.0 when LiteLLM connects from another container or host on the private network.

stdio

Run in stdio mode for a local MCP client that launches the process directly.

For interactive development, use the MCP Inspector:

uv run mcp dev src/mcp_zotero/server.py

Test

uv run pytest

API behavior

The client sends these headers to Zotero:

Zotero-API-Key: ...
Zotero-API-Version: 3

It observes Zotero Backoff and Retry-After headers. It sends no more than four concurrent Zotero requests. Parent items are retrieved in batches of at most 50 keys, as required by the API.

A PDF can have no synchronized text even when its attachment metadata exists. In this case, get_paper_text returns status="not_available".

Zotero documentation

• Web API v3 basics

• Full-text content requests