zotero-mcp

Read-only MCP server for browsing, searching, and exporting a Zotero library from AI assistants such as Claude. <!-- mcp-name: io.github.nadavWeisler/zotero-mcp -->

Features

• Read-only access to collections, saved searches, items, notes, attachments, tags, and citations
• Structured JSON responses (output_format="json") for AI clients that prefer machine-readable output
• Text responses by default for chat-oriented clients
• Pagination hints, filter validation, and normalized metadata fields
• Shared HTTP client with retry/backoff and clearer upstream error handling

Available tools

Tool	Description
list_collections	List non-search collections
list_saved_searches	List saved searches
list_items	List items with optional type/tag filters
list_collection_items	List items from a specific collection
list_saved_search_items	List items returned by a saved search
get_item	Fetch normalized metadata for a single item
get_note	Fetch note content for a note item
get_attachment	Fetch attachment metadata
search_items	Full-text or title/creator/year search
list_tags	List tags with item counts
get_item_children	List note/attachment children for an item
get_item_citation	Render a citation in a Zotero style such as APA or MLA
export_item	Export an item as BibTeX, BibLaTeX, RIS, MODS, Refer, or CSL JSON

Requirements

• Python 3.12+
• A Zotero Web API key
• Your numeric Zotero user or group library ID

Setup

1 — Get your API credentials

1. Sign in at zotero.org and open Settings → Feeds/API.
2. Create a new private key with read-only access to your library.
3. Note the generated key and your numeric User ID or Group ID.

2 — Set environment variables

Variable	Required	Default	Description
ZOTERO_API_KEY	✅	—	Zotero API key
ZOTERO_LIBRARY_ID	✅	—	Numeric user or group library ID
ZOTERO_LIBRARY_TYPE		user	user or group
ZOTERO_API_BASE		https://api.zotero.org	Override for alternate Zotero API bases
ZOTERO_MCP_LOG_LEVEL		WARNING	Python logging level for request/retry observability

export ZOTERO_API_KEY="your_api_key_here"
export ZOTERO_LIBRARY_ID="123456"
export ZOTERO_LIBRARY_TYPE="user"   # or "group"

3 — Install dependencies

With uv:

uv sync

With pip:

python -m pip install -e .

4 — Run the server

python main.py

Or via the installed package entrypoint:

python -m zotero_mcp

Client configuration

Claude Desktop

Add the following to claude_desktop_config.json:

{
  "mcpServers": {
    "zotero": {
      "command": "python",
      "args": ["/absolute/path/to/zotero-mcp/main.py"],
      "env": {
        "ZOTERO_API_KEY": "your_api_key_here",
        "ZOTERO_LIBRARY_ID": "123456",
        "ZOTERO_LIBRARY_TYPE": "user"
      }
    }
  }
}

Restart Claude Desktop after saving.

Generic stdio MCP clients

Any stdio-based MCP client can launch the server with:

{
  "command": "python",
  "args": ["/absolute/path/to/zotero-mcp/main.py"],
  "env": {
    "ZOTERO_API_KEY": "your_api_key_here",
    "ZOTERO_LIBRARY_ID": "123456",
    "ZOTERO_LIBRARY_TYPE": "user"
  }
}

Structured output

Every tool supports:

• output_format="text" (default)
• output_format="json"

JSON mode is useful when an MCP client or agent wants explicit paging and normalized metadata:

{
  "paging": {
    "start": 0,
    "returned": 25,
    "total": 143,
    "next_start": 25,
    "has_more": true
  }
}

Common workflows

• Browse a collection: list_collection_items(collection_key="ABCD1234")
• Explore saved searches: list_saved_searches(output_format="json")
• Fetch richer child data: get_item_children(item_key="ABCD1234", item_type="note")
• Export a reference: export_item(item_key="ABCD1234", export_format="bibtex")
• Render a formatted citation: get_item_citation(item_key="ABCD1234", style="mla")

Example prompts for AI clients

• “List my saved searches as JSON.”
• “Show the latest 10 journal articles tagged ai.”
• “Export item ABCD1234 as BibTeX.”
• “Get the note content for Zotero item NOTE1234.”
• “List attachments for item ABCD1234.”

Tool reference

Common pagination and output parameters

Most list tools support:

Parameter	Type	Default	Description
start	int	0	Pagination offset
limit	int	25 or 100	Items per page (max 100)
output_format	str	text	text or json

list_items

Parameter	Type	Default	Description
item_type	str	—	Filter by Zotero item type
tag	str	—	Filter by tag name
sort	str	dateModified	dateModified, title, creator, date
direction	str	desc	asc or desc

list_collection_items / list_saved_search_items

Parameter	Type	Default	Description
collection_key / search_key	str	—	Target Zotero key
sort	str	dateModified	dateModified, title, creator, date
direction	str	desc	asc or desc

get_item

Parameter	Type	Default	Description
item_key	str	—	Zotero item key
expanded	bool	false	Include abstract text

get_item_children

Parameter	Type	Default	Description
item_key	str	—	Parent Zotero item key
item_type	str	—	Optional attachment or note filter

search_items

Parameter	Type	Default	Description
query	str	—	Search terms
qmode	str	everything	everything or titleCreatorYear
tag	str	—	Optional tag filter
item_type	str	—	Optional item type filter

get_item_citation

Parameter	Type	Default	Description
item_key	str	—	Zotero item key
style	str	apa	Citation style
locale	str	—	Optional locale such as en-US
linkwrap	bool	false	Request wrapped links when supported

export_item

Parameter	Type	Default	Description
item_key	str	—	Zotero item key
export_format	str	bibtex	bibtex, biblatex, ris, mods, refer, csljson

Known limitations

• Read-only: creating, editing, or deleting items is not supported.
• Attachment binaries: attachment file content is not downloaded.
• Saved searches: the server exposes saved searches as special collections and uses their keys for item listing.
• Single library scope: one configured user or group library per server process.

Development

Install dev dependencies

With uv:

uv sync --extra dev

With pip:

python -m pip install -e ".[dev]"

Run tests

python -m pytest tests/ -v

Build the package

python -m build

Project layout

zotero-mcp/
├── main.py               # Compatibility entry point
├── server.json           # MCP Registry metadata
├── zotero_mcp/
│   ├── __main__.py       # Packaged entry point
│   ├── client.py         # Zotero Web API v3 client
│   ├── config.py         # Constants and version metadata
│   ├── formatters.py     # Text + structured output normalization
│   └── tools.py          # MCP tool implementations
└── tests/
    ├── test_client.py
    ├── test_formatters.py
    ├── test_main.py
    ├── test_server.py
    └── test_tools.py

Changelog

0.2.0

• Added collection-scoped listing and saved-search discovery tools
• Added dedicated note, attachment, citation, and export tools
• Added structured JSON output across the tool surface
• Added stricter validation, shared HTTP client reuse, and retry/backoff logging
• Expanded automated coverage and CI expectations

0.1.0

• Initial Zotero MCP server implementation
• Six read-only tools for browsing items, collections, tags, and children
• Automatic retry on rate-limit (HTTP 429) and transient network errors

MCP Registry publishing

This repository includes a server.json file for MCP Registry publication under:

• name: io.github.nadavWeisler/zotero-mcp
• registryType: pypi
• identifier: nadavweisler-zotero-mcp

To publish a new release:

1. Publish version 0.2.0 (or newer) of nadavweisler-zotero-mcp to PyPI.
2. Install mcp-publisher.
3. Run:
   • mcp-publisher login github
   • mcp-publisher publish

v2 roadmap ideas

• Optional write operations behind explicit opt-in safeguards
• Multi-library support
• More advanced search composition for large libraries
• Client-selectable output modes tuned for specific MCP consumers