# ChromaDB MCP Server

A comprehensive Model Context Protocol (MCP) server that exposes ChromaDB vector database operations as MCP tools. This server allows AI assistants and other MCP clients to interact with ChromaDB databases through a standardized interface.

## Features

- **Collection Management**: Create, list, get, and delete collections
- **Document Operations**: Add, query, update, and delete documents
- **Vector Similarity Search**: Perform semantic searches using text or embedding queries
- **Metadata Filtering**: Filter queries by document metadata and content
- **Collection Statistics**: Get information about collections and their contents
- **Async/Await Support**: Built with asyncio for high performance

## Installation

1. **Create and activate a virtual environment:**
```bash
# Create virtual environment
python3 -m venv venv

# Activate the virtual environment
source venv/bin/activate
```

2. **Install the project using Hatch:**
```bash
# Install in development mode with all dependencies
pip install hatch
hatch env create
hatch run pip install -e .

# Or simply use pip with the project (after installing hatch)
pip install -e ".[dev]"

# Optional: Install additional embedding providers
pip install -e ".[openai]"          # For OpenAI embeddings
pip install -e ".[cohere]"          # For Cohere embeddings (LangChain compatible)
pip install -e ".[instructor]"      # For Instructor embeddings (LangChain compatible)
pip install -e ".[sentence-transformers]"  # For Sentence Transformers
pip install -e ".[huggingface]"     # For HuggingFace models
```

3. **Verify installation:**
```bash
hatch run chroma-mcp-server --help
# or
python -m app.chroma_mcp_server --help
```

4. **Run the server:**
```bash
# Using Hatch (recommended)
hatch run serve

# Or using Python directly (make sure virtual env is activated)
python -m app.chroma_mcp_server

# Or using the script entry point
chroma-mcp-server

# Run with specific transport (stdio, http, sse)
python -m app.chroma_mcp_server stdio
python -m app.chroma_mcp_server http 127.0.0.1 8000
python -m app.chroma_mcp_server sse 127.0.0.1 8000
```

2. Ensure ChromaDB is running. You can start it locally:
```bash
# For local persistent storage
chroma run --path ./chroma_data

# Or for in-memory (will be lost on restart)
chroma run
```

## ChromaDB Connection Modes

The server supports multiple ChromaDB connection modes:

### HTTP Mode (Default)
- Connects to a running ChromaDB server via HTTP
- Requires `CHROMA_HOST` and `CHROMA_PORT` (default: localhost:8000)
- Best for: Production, shared databases, remote servers

### Persistent Mode
- Uses local ChromaDB persistent client (no network needed)
- Requires `CHROMA_PERSIST_DIRECTORY` or defaults to `./chroma_db`
- Best for: Local development, single-user scenarios

### Memory Mode
- Uses in-memory ChromaDB (fastest, data lost on restart)
- No configuration needed - just set `CHROMA_MODE=memory`
- Best for: Testing, temporary data, quick prototyping

### Configuration Precedence and CLI Options

- CLI flags override environment variables from `.env`.
- If a CLI option is provided, it takes precedence over any `.env` value.

Available CLI overrides:

```bash
# Backend selection
--chroma-mode [http|persistent|memory]

# HTTP mode parameters (when --chroma-mode=http)
--chroma-host <host>
--chroma-port <port>

# Persistent mode parameter (when --chroma-mode=persistent)
--chroma-persist-directory <path>

## Usage Examples

```bash
# HTTP mode (default) - connect to ChromaDB server
hatch run chroma-mcp-server stdio --chroma-mode http --chroma-host localhost --chroma-port 8000

# Persistent mode - local database with persistence
hatch run chroma-mcp-server stdio --chroma-mode persistent --chroma-persist-directory ./my_data

# Memory mode - fast in-memory database
hatch run chroma-mcp-server stdio --chroma-mode memory

# SSE transport with persistent backend and explicit host/port
hatch run chroma-mcp-server sse 0.0.0.0 8091 --chroma-mode persistent --chroma-persist-directory ./chroma_data

# HTTP transport with explicit host/port and HTTP backend
hatch run chroma-mcp-server http 127.0.0.1 8090 --chroma-mode http --chroma-host localhost --chroma-port 8000

# CLI options override .env values
hatch run chroma-mcp-server stdio --chroma-mode http --chroma-host my-chroma-server.com --chroma-port 8080
```
- `CHROMA_HOST`: ChromaDB host (default: localhost)
- `CHROMA_PORT`: ChromaDB port (default: 8000) - **optional, can be omitted**
- `CHROMA_PERSIST_DIRECTORY`: Path for persistent storage (optional)
- `CHROMA_MODE`: Connection mode - `http` (default), `persistent`, or `memory`
- `DEFAULT_EMBEDDING_PROVIDER`: Default embedding provider (sentence-transformers, openai, cohere, instructor, huggingface)
- `DEFAULT_EMBEDDING_MODEL`: Default embedding model name
- `OPENAI_API_KEY`: OpenAI API key for OpenAI embeddings
- `COHERE_API_KEY`: Cohere API key for Cohere embeddings

## Development

### Using Hatch Environments

This project uses Hatch for environment management and development workflow:

```bash
# Create and enter development environment
hatch shell

# Run tests
hatch run test

# Format code
hatch run format

# Lint code
hatch run lint

# Type check
hatch run type-check

# Run server in development mode
hatch run python -m app.chroma_mcp_server
```

### Virtual Environment Management

```bash
# Create virtual environment
python -m venv venv

# Activate the virtual environment
source venv/bin/activate

# Deactivate when done
deactivate
```

### Project Structure

- `src/app/` - Main application package
  - `chroma_mcp_server.py` - Main MCP server implementation
  - `__init__.py` - Package initialization
- `pyproject.toml` - Project configuration and dependencies
- `example_usage.py` - Usage examples and demonstrations
- Configuration files for MCP clients in JSON format

## Available MCP Tools

### Collection Management

#### `list_collections()`
Lists all collections in the database with their metadata.

**Returns**: JSON array of collection information

#### `create_collection(name, metadata, embedding_config)`
Creates a new collection.

**Parameters**:
- `name` (str): Collection name
- `metadata` (dict, optional): Collection metadata
- `embedding_config` (dict, optional): Embedding function configuration:
  - `provider` (str): "sentence-transformers", "openai", "cohere", "instructor", or "huggingface"
  - `model` (str): Model name (e.g., "all-MiniLM-L6-v2", "text-embedding-ada-002", "embed-english-v3.0")
  - `api_key` (str, optional): API key for provider services

#### `get_collection(name)`
Gets information about a specific collection.

**Parameters**:
- `name` (str): Collection name

**Returns**: Collection information including document count

#### `delete_collection(name)`
Deletes a collection and all its documents.

**Parameters**:
- `name` (str): Collection name

### Document Operations

#### `add_documents(collection_name, documents)`
Adds documents to a collection.

**Parameters**:
- `collection_name` (str): Target collection name
- `documents` (array): Array of document objects with:
  - `id` (str): Unique document identifier
  - `content` (str): Document text content
  - `metadata` (dict, optional): Document metadata
  - `embedding` (array, optional): Pre-computed embedding vector

#### `query_collection(query)`
Performs similarity search on a collection.

**Parameters**:
- `query` (object): Query configuration with:
  - `collection_name` (str): Target collection
  - `query_texts` (array, optional): Text queries for semantic search
  - `query_embeddings` (array, optional): Embedding vectors for direct similarity search
  - `n_results` (int, default: 10): Number of results to return
  - `where` (dict, optional): Metadata filters
  - `where_document` (dict, optional): Document content filters

**Returns**: Query results with documents, metadata, and similarity scores

#### `update_document(update)`
Updates an existing document.

**Parameters**:
- `update` (object): Update configuration with:
  - `collection_name` (str): Target collection
  - `document_id` (str): Document to update
  - `content` (str, optional): New content
  - `metadata` (dict, optional): New metadata
  - `embedding` (array, optional): New embedding

#### `delete_documents(collection_name, document_ids)`
Deletes documents from a collection.

**Parameters**:
- `collection_name` (str): Target collection
- `document_ids` (array): Array of document IDs to delete

#### `get_document(collection_name, document_id)`
Retrieves a specific document.

**Parameters**:
- `collection_name` (str): Target collection
- `document_id` (str): Document ID to retrieve

### Utility Tools

#### `collection_stats(collection_name)`
Gets statistics for a collection.

**Parameters**:
- `collection_name` (str): Target collection

#### `peek_collection(collection_name, limit)`
Peeks at the first few documents in a collection.

**Parameters**:
- `collection_name` (str): Target collection
- `limit` (int, default: 10): Maximum documents to return

## Usage Examples

### LangChain-Compatible Embedding Examples

```python
# Create collection with Cohere embeddings (popular in LangChain)
await create_collection("docs", embedding_config={
    "provider": "cohere",
    "model": "embed-english-v3.0",
    "api_key": "your-cohere-key"
})

# Create collection with Instructor embeddings (optimized for instructions)
await create_collection("instructions", embedding_config={
    "provider": "instructor", 
    "model": "hkunlp/instructor-xl"
})

# Create collection with OpenAI embeddings (standard in LangChain)
await create_collection("embeddings", embedding_config={
    "provider": "openai",
    "model": "text-embedding-ada-002"
})

# Environment-based configuration (great for LangChain integration)
import os
os.environ["DEFAULT_EMBEDDING_PROVIDER"] = "cohere"
os.environ["COHERE_API_KEY"] = "your-key"
os.environ["DEFAULT_EMBEDDING_MODEL"] = "embed-english-v3.0"
```

### Adding and Querying Documents

```python
# Add documents
documents = [
    {
        "id": "doc1",
        "content": "This is a sample document about AI",
        "metadata": {"category": "tech", "year": 2024}
    },
    {
        "id": "doc2",
        "content": "Another document about machine learning",
        "metadata": {"category": "tech", "year": 2024}
    }
]
await add_documents("my_documents", documents)

# Query by text
query = {
    "collection_name": "my_documents",
    "query_texts": ["artificial intelligence"],
    "n_results": 5
}
results = await query_collection(query)

# Query with metadata filters
query = {
    "collection_name": "my_documents",
    "query_texts": ["technology"],
    "where": {"category": "tech"},
    "n_results": 10
}
results = await query_collection(query)
```

### Document Management

```python
# Update a document
await update_document({
    "collection_name": "my_documents",
    "document_id": "doc1",
    "content": "Updated content about AI and machine learning",
    "metadata": {"category": "tech", "year": 2024, "updated": True}
})

# Get a specific document
doc = await get_document("my_documents", "doc1")

# Delete documents
await delete_documents("my_documents", ["doc1", "doc2"])
```

## Running the Server

Start the MCP server:

```bash
python -m app.chroma_mcp_server
```

The server will start and expose MCP tools that can be used by compatible MCP clients.

## Transport Modes

The server supports multiple transport protocols for different use cases:

### STDIO Transport (Default)
- **Best for**: Local development, Claude Desktop integration
- **Usage**: `python -m app.chroma_mcp_server stdio`
- **Characteristics**: Direct communication via standard input/output

### HTTP Transport
- **Best for**: Network accessibility, multiple concurrent clients
- **Usage**: `python -m app.chroma_mcp_server http 127.0.0.1 8000`
- **Access**: Available at `http://127.0.0.1:8000/mcp`

### SSE Transport (Server-Sent Events)
- **Best for**: Real-time streaming, web integration
- **Usage**: `python -m app.chroma_mcp_server sse 127.0.0.1 8000`
- **Note**: Legacy transport, HTTP is recommended for new projects

## MCP Client Configuration

### Claude Desktop Configuration

To use this server with Claude Desktop or other MCP clients that support stdio protocol, add the following configuration to your MCP client config file:

**Basic Configuration** (`claude-desktop-config.json`):
```json
{
  "mcpServers": {
    "chroma-db": {
      "command": "python",
      "args": ["-m", "app.chroma_mcp_server", "stdio"],
      "env": {
        "CHROMA_HOST": "localhost",
        "CHROMA_PORT": "8000"
      }
    }
  }
}
```

**SSE Configuration** for network access:
```json
{
  "mcpServers": {
    "chroma-sse": {
      "command": "python",
      "args": ["-m", "app.chroma_mcp_server", "sse", "127.0.0.1", "8091", "--chroma-mode", "persistent", "--chroma-persist-directory", "./chroma_data"],
      "cwd": "/home/zoomrec/projects/chroma-mcp-server",
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}
```

### Configuration Parameters

- **command**: The command to run (usually `python`)
- **args**: Command line arguments (path to server script)
- **cwd**: Working directory (optional, useful for relative paths)
- **env**: Environment variables for ChromaDB connection:
  - `CHROMA_HOST`: ChromaDB server hostname
  - `CHROMA_PORT`: ChromaDB server port
  - `CHROMA_PERSIST_DIRECTORY`: Local persistent storage path
  - `LOG_LEVEL`: Logging level (DEBUG, INFO, WARNING, ERROR)

## Integration with LangChain

This MCP server is designed to work seamlessly with LangChain applications. The embedding providers are specifically chosen to match LangChain's commonly used embeddings:

### Supported LangChain Embeddings

- **OpenAI**: `text-embedding-ada-002` - Most popular in LangChain
- **Cohere**: `embed-english-v3.0` - High-performance alternative
- **Instructor**: `hkunlp/instructor-xl` - Instruction-tuned embeddings
- **Sentence Transformers**: `all-MiniLM-L6-v2` - Local, no API required
- **HuggingFace**: Any model from the Hub

### LangChain Integration Example

```python
# In your LangChain application
from langchain.vectorstores import Chroma
from langchain.embeddings import OpenAIEmbeddings, CohereEmbeddings

# Use with LangChain's Chroma wrapper
embeddings = OpenAIEmbeddings(
    model="text-embedding-ada-002",
    openai_api_key="your-key"
)

# Create Chroma collection via MCP server first
# Then use it in LangChain
vectorstore = Chroma(
    collection_name="my_docs",
    embedding_function=embeddings,
    client=your_chroma_client
)
```

## Integration with AI Assistants

This server is designed to work with AI assistants that support the Model Context Protocol. Once running, the assistant can:

1. Discover available tools automatically
2. Use the tools to interact with ChromaDB
3. Perform vector similarity searches
4. Manage collections and documents
5. Build RAG (Retrieval-Augmented Generation) applications

## Error Handling

The server includes comprehensive error handling and will return descriptive error messages for:

- Connection issues with ChromaDB
- Invalid collection or document IDs
- Query parameter errors
- Network timeouts

## Performance Considerations

- Uses async/await for non-blocking operations
- Supports both local persistent and remote ChromaDB instances
- Configurable query result limits
- Efficient batch operations for document management

## Troubleshooting

### Common Issues

1. **Connection refused**: Ensure ChromaDB is running on the specified host/port
2. **Collection not found**: Verify collection names are correct
3. **Document not found**: Check document IDs exist in the collection
4. **Import errors**: Ensure all dependencies are installed from pyproject.toml

### Logging

The server logs to stdout with INFO level by default. You can adjust logging by modifying the logging configuration in the server file.

## License

This project is open source and available under the MIT License.