# Zotero MCP Server

A Model Context Protocol (MCP) server for Zotero that provides semantic search capabilities using PostgreSQL with pg-vector and OpenAI/Ollama embeddings.

__This is a fork of the [excellent zotero-mcp project](https://github.com/54yyyu/zotero-mcp) with modifications to match my personal workflow (pg-vector instead of chroma, ollama and openai backend instead of local transformers, etc.). I am still in progress of refactoring to fit this project to my personal needs__

__THIS IS NOT THE OFFICIAL PROJECT AND MY MODIFICATIONY MAY HAVE BUGS__. I just use this version for my personal research projects.

At the moment I use the version in this repository against my own OpenAI
compatible [API gateway](https://github.com/tspspi/mini-apigw).

## Features

- **Full Zotero Integration**: Access your Zotero library through MCP tools
- **Semantic Search**: AI-powered semantic search using PostgreSQL + pg-vector
- **Multiple Embedding Providers**: Support for OpenAI and Ollama embeddings
- **Lightweight Architecture**: Removed heavy ML dependencies (torch, transformers)
- **High Performance**: PostgreSQL backend with optimized vector operations
- **Flexible Configuration**: Support for local and remote database instances

## Quick Start

### Prerequisites

- Python 3.10+
- PostgreSQL 15+ with pg-vector extension
- Zotero desktop application or Zotero Web API credentials
- OpenAI API key or Ollama installation

### Installation

```
pip install -e .
```

### PostgreSQL Setup

If you have access to a PostgreSQL instance with pg-vector:

```sql
-- Connect to your PostgreSQL instance
CREATE DATABASE zotero_mcp;
CREATE USER zotero_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE zotero_mcp TO zotero_user;

-- Enable pg-vector extension
\c zotero_mcp
CREATE EXTENSION vector;
```

### Configuration

Run the interactive setup:

```bash
zotero-mcp setup
```

### Usage with Claude Desktop

```json
{
  "mcpServers": {
    "zotero": {
      "command": "/path/to/zotero-mcp",
      "env": {
        "ZOTERO_DB_HOST": "your_host",
        "ZOTERO_DB_NAME": "zotero_mcp",
        "ZOTERO_EMBEDDING_PROVIDER": "ollama",
        "OLLAMA_HOST": "your_ollama_host"
      }
    }
  }
}
```

## Configuration

### Database Configuration

Create `~/.config/zotero-mcp/config.json`:

```json
{
  "database": {
    "host": "localhost",
    "port": 5432,
    "database": "zotero_mcp",
    "username": "zotero_user",
    "password": "your_password",
    "schema": "public",
    "pool_size": 5
  },
  "embedding": {
    "provider": "ollama",
    "openai": {
      "api_key": "sk-...",
      "model": "text-embedding-3-small",
      "batch_size": 100
    },
    "ollama": {
      "host": "192.168.1.189:8182",
      "model": "nomic-embed-text",
      "timeout": 60
    }
  },
  "chunking": {
    "chunk_size": 1000,
    "overlap": 100,
    "min_chunk_size": 100,
    "max_chunks_per_item": 10,
    "chunking_strategy": "sentences"
  },
  "semantic_search": {
    "similarity_threshold": 0.7,
    "max_results": 50,
    "update_config": {
      "auto_update": false,
      "update_frequency": "manual",
      "batch_size": 50,
      "parallel_workers": 4
    }
  }
}
```

## Available Tools

### Core Zotero Tools

- `zotero_search_items` - Search items by text query
- `zotero_search_by_tag` - Search items by tags
- `zotero_get_item_metadata` - Get item details and metadata
- `zotero_get_item_fulltext` - Extract full text from attachments
- `zotero_get_collections` - List all collections
- `zotero_get_collection_items` - Get items in a collection
- `zotero_get_recent` - Get recently added items
- `zotero_get_tags` - List all tags
- `zotero_batch_update_tags` - Bulk update tags

### Semantic Search Tools

- `zotero_semantic_search` - **AI-powered semantic search**
- `zotero_update_search_database` - Update embedding database  
- `zotero_get_search_database_status` - Check database status

### Advanced Tools

- `zotero_get_annotations` - Extract annotations from PDFs
- `zotero_get_notes` - Retrieve notes
- `zotero_search_notes` - Search through notes
- `zotero_create_note` - Create new notes
- `zotero_advanced_search` - Complex multi-criteria search

## Semantic Search

The semantic search uses PostgreSQL with pg-vector for efficient vector similarity search:

### Database Population

```bash
# Initial database population
zotero-mcp update-db --force-rebuild

# Incremental updates
zotero-mcp update-db

# Update with limit (for testing)
zotero-mcp update-db --limit 100

# Check status
zotero-mcp status
```

## Embedding Providers

### OpenAI (Recommended)

```json
{
  "embedding": {
    "provider": "openai",
    "openai": {
      "api_key": "sk-...",
      "model": "text-embedding-3-small",
      "batch_size": 100,
      "rate_limit_rpm": 3000
    }
  }
}
```

**Models Available**:
- `text-embedding-3-small` (1536 dimensions) - Fast and efficient
- `text-embedding-3-large` (3072 dimensions) - Higher quality
- `text-embedding-ada-002` (1536 dimensions) - Legacy model

### Ollama (Local)

```json
{
  "embedding": {
    "provider": "ollama", 
    "ollama": {
      "host": "http://localhost:11434",
      "model": "nomic-embed-text",
      "timeout": 60
    }
  }
}
```

**Popular Models**:
- `nomic-embed-text` - Good general purpose embeddings
- `all-minilm` - Lightweight and fast
- `mxbai-embed-large` - High quality embeddings

To install Ollama models:
```bash
ollama pull nomic-embed-text
```

## Architecture

### Component Overview

```
┌─────────────────┐    ┌─────────────────┐
│   Claude MCP    │───▶│  FastMCP Server │
│    Client       │    │   (server.py)   │
└─────────────────┘    └─────────────────┘
                               │
                               ▼
                    ┌─────────────────┐
                    │ Semantic Search │
                    │ (semantic_search.py) │
                    └─────────────────┘
                               │
                    ┌──────────┴──────────┐
                    ▼                     ▼
              ┌──────────────┐    ┌──────────────┐
              │ Vector Client│    │  Embedding   │
              │(vector_client)│    │   Service    │
              └──────────────┘    │(embedding_   │
                     │            │ service.py)  │
                     ▼            └──────────────┘
              ┌──────────────┐           │
              │ PostgreSQL   │           ▼
              │   + pgvector │    ┌──────────────┐
              └──────────────┘    │ OpenAI/Ollama│
                                  │   APIs       │
                                  └──────────────┘
```

### Database Schema

```sql
-- Core embeddings table
CREATE TABLE zotero_embeddings (
    id SERIAL PRIMARY KEY,
    item_key VARCHAR(50) UNIQUE NOT NULL,
    item_type VARCHAR(50) NOT NULL,
    title TEXT,
    content TEXT NOT NULL,
    content_hash VARCHAR(64) NOT NULL,
    embedding vector(1536),
    embedding_model VARCHAR(100) NOT NULL,
    embedding_provider VARCHAR(50) NOT NULL,
    metadata JSONB NOT NULL DEFAULT '{}',
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

-- Optimized indexes
CREATE INDEX idx_zotero_embedding_cosine 
    ON zotero_embeddings USING ivfflat (embedding vector_cosine_ops) 
    WITH (lists = 100);
CREATE INDEX idx_zotero_metadata_gin 
    ON zotero_embeddings USING gin(metadata);
```

## License

MIT License - see [LICENSE](LICENSE) file for details.