zotero-mcp

Read+write MCP server for Zotero. An MCP server with full write support for managing Zotero library from AI assistants.

It lets you create items, manage collections, find and merge duplicates, and import BibTeX from within Claude Code/Desktop, or any MCP-compatible client.

Uses the Zotero Web API (requires API key). Get the key at https://www.zotero.org/settings/keys.

Features

Search & Read

Tool	Description
search_items	Full-text search with collection, type, and tag filters
get_item	Detailed metadata or BibTeX export for a single item
get_collections	List all collections with hierarchy and item counts
get_collection_items	List items in a specific collection
find_duplicates	Find duplicates by title/DOI, or scan entire library
get_tags	List all tags with item counts

Write

Tool	Description
create_item	Create item from field data
create_item_from_doi	Create item by DOI (auto-fills metadata via Zotero translator + CrossRef)
import_bibtex	Import BibTeX entries into a collection
update_item	Update item fields with version conflict protection

Collections

Tool	Description
create_collection	Create a collection (with optional parent)
add_to_collections	Add an item to multiple collections at once
remove_from_collection	Remove item from collection (doesn't delete it)

Management

Tool	Description
merge_duplicates	Merge duplicates: transfer metadata, tags, collections to keeper, delete rest
delete_item	Delete an item

Installation

Requires Python 3.11+ and uv.

# Clone the repo
git clone https://github.com/BirdInTheTree/zotero-mcp.git
cd zotero-mcp
uv sync

Usage

Claude Code

claude mcp add zotero \
  -e ZOTERO_API_KEY=your-key \
  -e ZOTERO_USER_ID=your-user-id \
  -- uv run --directory /path/to/zotero-mcp python -m zotero_mcp

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "zotero": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/zotero-mcp", "python", "-m", "zotero_mcp"],
      "env": {
        "ZOTERO_API_KEY": "your-key",
        "ZOTERO_USER_ID": "your-user-id"
      }
    }
  }
}

Configuration

Variable	Required	Description
ZOTERO_API_KEY	yes	Zotero Web API key
ZOTERO_USER_ID	yes	Your Zotero user ID

Get your API key at https://www.zotero.org/settings/keys. Your user ID is shown on the same page.

Examples

Once connected, you can ask your AI assistant things like:

• "Search my Zotero for papers ..."
• "Create a new collection called ..."
• "Import this BibTeX into my collection"
• "Find duplicate items in my library and merge them"
• "Add this paper to both collections"
• "Look up DOI 10.1234/example and add it to my library"

Development

# Install with dev dependencies
uv sync --dev

# Run tests
uv run pytest tests/ -v

License

MIT