Zotero Keeper MCP Server

MCP Server for managing local Zotero libraries via AI Agents.

Installation

# Basic installation
pip install -e .

# With PubMed support
pip install -e ".[pubmed]"

# All features
pip install -e ".[all]"

Usage

# Run MCP server
python -m zotero_mcp

# Or use the CLI
zotero-keeper

Environment Variables

Copy .env.example to .env and configure:

# Local Zotero (default)
ZOTERO_HOST=localhost
ZOTERO_PORT=23119

# Remote Zotero
ZOTERO_HOST=<your-zotero-ip>
ZOTERO_PORT=23119

MCP Tools

🌟 Unified Import (NEW in v1.11.0)

Workflow:

# Step 1: Search with pubmed-search-mcp
results = search_literature("CRISPR gene therapy", limit=10)

# Step 2: Import to Zotero (ANY source works!)
import_articles(
    articles=results["articles"],
    collection_name="CRISPR Research",
    tags=["2024", "review"]
)

Supported sources: PubMed, Europe PMC, CORE, CrossRef, OpenAlex, Semantic Scholar, RIS

Core Tools

Smart Tools 🧠

Collection Tools

Saved Search Tools 🌟 (Local API Exclusive!)

Other Tools

💡 Smart Collection Feature

AI can suggest appropriate collections based on title, abstract, and tags!

Workflow Options

Option 1: Ask before saving

User: "Which collection should this AI paper go to?"
AI: suggest_collections(title="AI in Anesthesiology")
    → Suggests: "AI Research" (score: 85)

User: "Add it to AI Research"
AI: add_reference(..., collections=["ABC123KEY"])

Option 2: Auto-classify

User: "Add this paper and auto-classify"
AI: smart_add_with_collection(
        title="AI in Anesthesiology",
        auto_suggest_collection=True
    )
    → Automatically added to "AI Research"

Option 3: Specify by name

User: "Add to 'Machine Learning' collection"
AI: smart_add_with_collection(
        title="...",
        collection_name="Machine Learning"
    )

⚠️ Important Note

Since Local API cannot create collections:

1. Create collection structure in Zotero first
2. Let AI classify into existing collections

🌟 Saved Search Feature (Local API Exclusive!)

This is a unique feature only available via Local API - Web API cannot execute saved searches!

How It Works

1. Create Saved Search in Zotero (one-time setup)
2. AI executes it anytime via run_saved_search

Step-by-Step Guide

Step 1: Create Saved Search in Zotero

1. Open Zotero
2. Press Ctrl+Shift+F (or Edit → Advanced Search)
3. Set conditions (see examples below)
4. Click Save Search
5. Give it a memorable name (e.g., "Missing PDF")

Step 2: Use via AI

AI: "Which papers don't have PDFs?"
→ run_saved_search(search_name="Missing PDF")

AI: "What did I add this week?"
→ run_saved_search(search_name="Recent Additions")

Recommended Saved Searches

Create these once, use forever:

Condition Reference

Documentation

See main README for full documentation.