Chroma

community

Vector database server for semantic document search and metadata filtering, built on Chroma

Chroma MCP Server

A Model Context Protocol (MCP) server implementation that provides vector database capabilities through Chroma. This server enables semantic document search, metadata filtering, and document management with persistent storage.

Requirements

Python 3.8+
Chroma 0.4.0+
MCP SDK 0.1.0+

Components

Resources

The server provides document storage and retrieval through Chroma's vector database:

Stores documents with content and metadata
Persists data in
```
src/chroma/data
```
directory
Supports semantic similarity search

Tools

The server implements CRUD operations and search functionality:

Document Management

```
create_document
```
: Create a new document
- Required:
```
document_id
```
  ,
```
content
```
- Optional:
```
metadata
```
  (key-value pairs)
- Returns: Success confirmation
- Error: Already exists, Invalid input
```
read_document
```
: Retrieve a document by ID
- Required:
```
document_id
```
- Returns: Document content and metadata
- Error: Not found
```
update_document
```
: Update an existing document
- Required:
```
document_id
```
  ,
```
content
```
- Optional:
```
metadata
```
- Returns: Success confirmation
- Error: Not found, Invalid input
```
delete_document
```
: Remove a document
- Required:
```
document_id
```
- Returns: Success confirmation
- Error: Not found
```
list_documents
```
: List all documents
- Optional:
```
limit
```
  ,
```
offset
```
- Returns: List of documents with content and metadata

Search Operations

```
search_similar
```
: Find semantically similar documents
- Required:
```
query
```
- Optional:
```
num_results
```
  ,
```
metadata_filter
```
  ,
```
content_filter
```
- Returns: Ranked list of similar documents with distance scores
- Error: Invalid filter

Features

Semantic Search: Find documents based on meaning using Chroma's embeddings
Metadata Filtering: Filter search results by metadata fields
Content Filtering: Additional filtering based on document content
Persistent Storage: Data persists in local directory between server restarts
Error Handling: Comprehensive error handling with clear messages
Retry Logic: Automatic retries for transient failures

Installation

Install dependencies:

uv venv
uv sync --dev --all-extras

Configuration

Claude Desktop

Add the server configuration to your Claude Desktop config:

Windows:

C:\Users\<username>\AppData\Roaming\Claude\claude_desktop_config.json

MacOS:

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "chroma": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/MCP/server/community/chroma",
        "run",
        "chroma"
      ]
    }
  }
}

Data Storage

The server stores data in:

Windows:
```
src/chroma/data
```
MacOS/Linux:
```
src/chroma/data
```

Usage

Start the server:

uv run chroma

Use MCP tools to interact with the server:

# Create a document
create_document({
    "document_id": "ml_paper1",
    "content": "Convolutional neural networks improve image recognition accuracy.",
    "metadata": {
        "year": 2020,
        "field": "computer vision",
        "complexity": "advanced"
    }
})

# Search similar documents
search_similar({
    "query": "machine learning models",
    "num_results": 2,
    "metadata_filter": {
        "year": 2020,
        "field": "computer vision"
    }
})

Error Handling

The server provides clear error messages for common scenarios:

```
Document already exists [id=X]
```
```
Document not found [id=X]
```

Invalid input: Missing document_id or content

```
Invalid filter
```
```
Operation failed: [details]
```

Development

Testing

Run the MCP Inspector for interactive testing:

npx @modelcontextprotocol/inspector uv --directory C:/MCP/server/community/chroma run chroma

Use the inspector's web interface to:
- Test CRUD operations
- Verify search functionality
- Check error handling
- Monitor server logs

Building

Update dependencies:

uv compile pyproject.toml

Build package:

uv build

Contributing

Contributions are welcome! Please read our Contributing Guidelines for details on:

Code style
Testing requirements
Pull request process

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Servers

Brave Search

reference

Web and local search using Brave's Search API

View Details

Git

reference

Tools to read, search, and manipulate Git repositories

View Details

Google Drive

reference

File access and search capabilities for Google Drive

View Details

Aiven

official

Navigate your [Aiven projects](https://go.aiven.io/mcp-server) and interact with the PostgreSQL®, Apache Kafka®, ClickHouse® and OpenSearch® services

View Details

Apify

official

[Actors MCP Server](https://apify.com/apify/actors-mcp-server): Use 3,000+ pre-built cloud tools to extract data from websites, e-commerce, social media, search engines, maps, and more

View Details