What is Chroma

The Chroma MCP Server is an implementation of the Model Context Protocol that offers vector database capabilities for semantic document search, management, and metadata filtering using Chroma. It provides persistent storage for documents and allows users to store, retrieve, and manage documents effectively.

Use cases

This server is useful for academic research, content management systems, data retrieval applications, and any scenario requiring document organization and search based on semantic meaning. It is ideal for professionals who need to quickly find relevant documents from a large set based on complex queries.

How to use

To use the Chroma MCP Server, start by launching the server with the command ‘uv run chroma’. You can then perform document management operations such as creating, reading, updating, and deleting documents, as well as searching for similar documents using specific queries and optional filters through the provided MCP tools.

Key features

Key features include semantic search powered by Chroma embeddings, metadata and content filtering for refined searches, persistent storage of documents, robust error handling, and automatic retries for transient failures. The server supports efficient CRUD operations for document management.

Where to use

The server can be deployed in various environments, including local development setups, cloud servers, and desktop applications compatible with Claude Desktop. It is suitable for organizations and developers looking to enhance their applications with advanced document search and management capabilities.

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.