Chroma MCP Server

What is Chroma MCP Server about?

Chroma MCP Server implements a Model Context Protocol (MCP) service that leverages the Chroma vector store to persist documents, their metadata, and embeddings. It exposes CRUD operations and similarity‑search tools so clients can create, read, update, delete, list, and query documents based on semantic meaning.

How to use Chroma MCP Server?

Install dependencies
```
uv venv
uv sync --dev --all-extras
```
Start the server
```
uv run chroma
```
Interact via MCP tools – use the provided functions (create_document, read_document, update_document, delete_document, list_documents, search_similar) either from a Python client or through the MCP Inspector web UI.
Optional configuration – add the server entry to Claude Desktop’s claude_desktop_config.json as shown in the README to allow the desktop client to launch the server automatically.

Key features of Chroma MCP Server

Semantic Search – retrieve documents by meaning using Chroma embeddings.
Metadata Filtering – limit results with key‑value metadata criteria.
Content Filtering – additional text‑based filters on document content.
Persistent Storage – all data is saved under src/chroma/data and survives restarts.
Comprehensive Error Handling – clear messages for duplicate IDs, missing documents, invalid inputs, and filter errors.
Retry Logic – automatic retries for transient failures.
Testing Utilities – MCP Inspector integration for interactive testing of all operations.

Use cases of Chroma MCP Server

Knowledge‑base augmentation – store technical papers, FAQs, or internal docs and retrieve them via natural‑language queries.
Semantic recommendation engine – recommend similar articles or code snippets based on user input.
Metadata‑driven filtering – quickly narrow search results by year, domain, or custom tags.
Rapid prototyping of AI‑augmented apps – plug the server into any MCP‑compatible client to add vector‑search capabilities without building a database from scratch.

FAQ from the Chroma MCP Server

Q: What Python version is required? A: Python 3.8 or newer.

Q: Which Chroma version does it depend on? A: Chroma 0.4.0 or later.

Q: How are embeddings generated? A: Chroma handles embedding creation internally using the configured model; the server only stores the resulting vectors.

Q: Where is the data stored? A: In the src/chroma/data directory on the host machine (same path for Windows, macOS, and Linux).

Q: Can I run the server inside a container? A: Yes – ensure the container has Python 3.8+, uv, and the project files, then execute uv run chroma as the entrypoint.

Q: How do I view logs or debug errors? A: The server prints logs to stdout; the MCP Inspector UI also displays request/response details and error messages.

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.

Chroma MCP Server