Skip to main content
Glama

mcp-zotero

MCP server for Zotero — 38 library tools + optional semantic search via local embeddings.

Install

Base (Zotero API tools only)

uv tool install mcp-zotero
uv tool install "mcp-zotero[rag]"

Adds 8 RAG tools for indexing PDFs and searching by meaning. Downloads a ~80MB embedding model on first use.

With OCR for scanned PDFs

uv tool install "mcp-zotero[rag,ocr]"

Adds docling-based OCR fallback for PDFs that contain scanned images instead of text.

Related MCP server: Zotero MCP Server

Configuration

Add to your Claude Code MCP settings (.mcp.json or ~/.claude/settings.json):

{
  "mcpServers": {
    "zotero": {
      "command": "mcp-zotero",
      "env": {
        "ZOTERO_LIBRARY_ID": "YOUR_LIBRARY_ID",
        "ZOTERO_LOCAL": "true",
        "ZOTERO_LOCAL_KEY": "YOUR_LOCAL_KEY",
        "ZOTERO_API_KEY": "YOUR_API_KEY",
        "ZOTERO_ATTACHMENTS_DIR": "~/Zotero/storage"
      }
    }
  }
}

Environment variables

Variable

Required

Default

Description

ZOTERO_LIBRARY_ID

Yes

—

Your Zotero library ID

ZOTERO_LIBRARY_TYPE

No

user

user or group

ZOTERO_LOCAL

No

true

Use Zotero Local API (requires Zotero app running)

ZOTERO_LOCAL_KEY

For reads

—

Local API key

ZOTERO_API_KEY

For writes

—

Web API key from zotero.org/settings/keys

ZOTERO_ATTACHMENTS_DIR

For RAG

—

Path to Zotero storage directory

RAG-only variables (when installed with [rag])

Variable

Default

Description

RAG_INDEX_DIR

~/.zotero-rag

Where to store index data

RAG_EMBEDDING_MODEL

all-MiniLM-L6-v2

Sentence transformer model

RAG_CHUNK_SIZE

512

Target chunk size in tokens

RAG_CHUNK_OVERLAP

50

Overlap between chunks

RAG_ENABLE_OCR

false

Enable docling OCR fallback for scanned PDFs

Tools

Base tools (38)

Always available. Covers the full Zotero API:

Search & browse: search_items, top_items, get_item, trash_items, deleted_items

Collections: list_collections, list_collections_top, list_collections_sub, get_collection, collection_items, collection_items_top, collection_tags, create_collections, update_collection, delete_collection, add_item_to_collection, remove_item_from_collection

Tags: list_tags, item_tags, delete_tags

Items: add_item, update_item, delete_item

Attachments: download_attachments, attach_file, attach_linked_file

Schema: item_types, item_fields, item_type_fields, creator_fields, item_creator_types, item_attachment_link_modes

Saved searches: list_searches, list_groups, create_saved_search, delete_saved_search

System: ping, health_check

RAG tools (8)

Available when installed with [rag]. Semantic search across your PDF library:

Tool

Description

index_library

Index a collection or entire library

index_items

Index specific items by key

remove_from_index

Remove items from the index

semantic_search

Search passages by meaning

get_chunk_context

Get surrounding text for a search result

find_similar_chunks

Find similar passages across documents

index_status

Get index statistics

list_indexed_items

List all indexed items

Development

git clone https://github.com/nealcaren/mcp-zotero.git
cd mcp-zotero
uv venv && uv pip install -e ".[dev,rag]"
pytest

License

MIT

Available Tools

38 tools
add_itemB

Add an item to Zotero. Optionally attach files (best-effort).

Inputs: req (required). Returns: result

add_item_to_collectionC

Add an item to a collection.

Inputs: req (required). Returns: result

attach_fileC

Attach a local file to an existing item (best-effort).

Inputs: req (required). Returns: result

attach_linked_fileC

Attach a linked (non-uploaded) local file to an existing item.

Inputs: req (required). Returns: result

collection_itemsC

Retrieve items in a collection.

Inputs: req (required). Returns: result

collection_items_topB

Retrieve top-level items in a collection.

Inputs: req (required). Returns: result

collection_tagsB

Retrieve tags for a collection.

Inputs: req (required). Returns: result

create_collectionsD

Create collections.

Inputs: req (required). Returns: result

creator_fieldsC

Retrieve creator fields.

Inputs: no named parameters. Returns: result

delete_collectionC

Delete a collection.

Inputs: req (required). Returns: result

deleted_itemsC

Retrieve deleted items (requires since).

Inputs: req (required). Returns: result

delete_itemB

Delete an item.

Inputs: req (required). Returns: result

delete_tagsD

Delete tags.

Inputs: req (required). Returns: result

download_attachmentsC

Download all file attachments for an item to a local directory.

Inputs: req (required). Returns: result

get_collectionC

Retrieve a collection.

Inputs: req (required). Returns: result

get_itemC

Retrieve a single item and (optionally) its children.

Inputs: req (required). Returns: result

health_checkA

Validate configuration without making API calls.

Inputs: no named parameters. Returns: result

item_creator_typesC

Retrieve creator types for an item type.

Inputs: req (required). Returns: result

item_fieldsB

Retrieve item fields.

Inputs: no named parameters. Returns: result

item_tagsB

Retrieve tags for a specific item.

Inputs: req (required). Returns: result

item_type_fieldsC

Retrieve fields for an item type.

Inputs: req (required). Returns: result

item_typesB

Retrieve item types.

Inputs: no named parameters. Returns: result

list_collectionsC

Retrieve collections.

Inputs: req (required). Returns: result

list_collections_subB

Retrieve subcollections for a collection.

Inputs: req (required). Returns: result

list_collections_topC

Retrieve top-level collections.

Inputs: req (required). Returns: result

list_groupsC

Retrieve user groups.

Inputs: req (required). Returns: result

list_searchesC

Retrieve saved searches.

Inputs: req (required). Returns: result

list_tagsC

Retrieve tags.

Inputs: req (required). Returns: result

pingA

Basic liveness check.

Inputs: no named parameters. Returns: result

remove_item_from_collectionC

Remove an item from a collection.

Inputs: req (required). Returns: result

search_itemsC

Search items by free-text query.

Inputs: req (required). Returns: result

top_itemsC

Retrieve top-level items.

Inputs: req (required). Returns: result

trash_itemsC

Retrieve items in the trash.

Inputs: req (required). Returns: result

update_collectionC

Update a collection's name or parent.

Inputs: req (required). Returns: result

update_itemC

Modify fields on an existing item.

Inputs: req (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 38 tools

    Disambiguation5/5

    Each tool has a clear, distinct purpose. Operations for items, collections, tags, and saved searches are all separated, with no overlapping functionality.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case, such as add_item, list_collections, delete_tag, etc. No mixing of conventions.

    Tool Count4/5

    38 tools is on the higher side but justified by the breadth of Zotero's API. Each tool serves a specific function, so the count, while large, is not excessive for a full-featured reference manager integration.

    Completeness5/5

    The tool set covers nearly all essential operations: full CRUD for items and collections, tag management, file attachments, saved searches, and metadata queries. No obvious gaps in core reference management workflows.

    Related MCP Connectors

    Related MCP Servers