Zotero MCP Server

A Model Context Protocol (MCP) server for Zotero, written in Rust. This server enables AI assistants like Claude Desktop and Cursor to interact with your Zotero library through a standardized interface.

Features

• 15 MCP tools for comprehensive Zotero library management
• Dual transport: stdio (default) and HTTP server modes
• Auto-detection: Automatically detects library ID from API key
• WebDAV support: Upload PDFs directly to your WebDAV server
• Paper import: Add papers by DOI, arXiv ID, or ISBN with automatic metadata extraction
• Smart search: Unified search across text, tags, citation keys, and advanced conditions

Installation

From Git

cargo install --git https://github.com/yousiki/zotero-mcp-rs

From Source

git clone https://github.com/yousiki/zotero-mcp-rs.git
cd zotero-mcp-rs
cargo build --release
# Binary will be at target/release/zotero-mcp-rs

Docker

1. Quick Start

docker run --rm -i -e ZOTERO_API_KEY=your_key ghcr.io/yousiki/zotero-mcp-rs

2. Available Images

• ghcr.io/yousiki/zotero-mcp-rs:latest - Latest stable release
• ghcr.io/yousiki/zotero-mcp-rs:edge - Latest development build
• ghcr.io/yousiki/zotero-mcp-rs:0.1.0 - Specific version

3. Claude Desktop Docker Config

{
  "mcpServers": {
    "zotero": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "ZOTERO_API_KEY=your_key", "ghcr.io/yousiki/zotero-mcp-rs"]
    }
  }
}

4. HTTP Mode

docker run --rm -p 3000:3000 \
  -e ZOTERO_API_KEY=your_key \
  -e MCP_TRANSPORT=http \
  ghcr.io/yousiki/zotero-mcp-rs

5. With WebDAV

docker run --rm -i \
  -e ZOTERO_API_KEY=your_key \
  -e WEBDAV_URL=https://your-webdav.com \
  -e WEBDAV_USERNAME=user \
  -e WEBDAV_PASSWORD=pass \
  ghcr.io/yousiki/zotero-mcp-rs

Important Notes

• Use -i flag for stdio mode (keeps stdin open)
• Do NOT use -t flag (corrupts stdio protocol)
• All config is via environment variables

Configuration

Environment Variables

Getting a Zotero API Key

1. Go to https://www.zotero.org/settings/keys
2. Click "Create new private key"
3. Grant appropriate permissions (read/write access to library)
4. Copy the generated key

MCP Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "zotero": {
      "command": "zotero-mcp-rs",
      "env": {
        "ZOTERO_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "zotero": {
      "command": "zotero-mcp-rs",
      "env": {
        "ZOTERO_API_KEY": "your_api_key_here"
      }
    }
  }
}

HTTP Mode

For HTTP transport (useful for remote access or containerized deployments):

MCP_TRANSPORT=http PORT=3000 zotero-mcp-rs

Then configure your MCP client to connect to http://localhost:3000/mcp.

Available Tools

Search

Items

Annotations & Notes

Collections

Library

Paper Management

Development

Prerequisites

• Rust 1.85+ (edition 2024)
• Cargo

Building

cargo build

Running Tests

cargo test

Linting

cargo clippy -- -D warnings

Formatting

cargo fmt

Architecture

The project follows a modular architecture:

• clients/: HTTP clients for Zotero API and WebDAV
• services/: Business logic (arXiv, CrossRef, PDF parsing, search)
• tools/: MCP tool handlers (one file per tool category)
• shared/: Common types, formatters, and utilities

See AGENTS.md for detailed architecture documentation and guides for adding new tools.

License

MIT

Acknowledgments

This project was inspired by zotero-mcp and references code from zotero/translation-server. Special thanks to oh-my-openagent for the excellent opencode plugin, and to Xiaomi for their powerful MIMO-V2-Pro model.