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?

1. Install dependencies

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

2. Start the server

   uv run chroma
   

3. 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.
4. 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.

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

1. 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

1. Start the server:

uv run chroma

2. 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

1. Run the MCP Inspector for interactive testing:

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

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

Building

1. Update dependencies:

uv compile pyproject.toml

2. 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.