📌Overview

Purpose: To provide a Model Context Protocol (MCP) server implementation that facilitates efficient document management and semantic search capabilities through a vector database.

Overview: The Chroma MCP Server leverages Chroma’s capabilities to deliver robust functionalities for semantic document search and management, including persistent storage and comprehensive error handling. It is designed to support a wide array of document operations, enhancing user experience in various applications.

Key Features:

• Semantic Search: Utilizes Chroma's embeddings to allow users to find documents based on their meaning, ensuring relevant search results.

• Metadata Filtering: Empowers users to narrow search results by applying filters based on specific metadata fields, enhancing the precision of search outcomes.

• Content Filtering: Offers additional filtering capabilities based on document content to further refine retrieval results.

• Persistent Storage: Ensures data is retained in a local directory between server restarts, making it reliable for continuous use.

• Error Handling: Includes a robust error handling system that provides clear feedback for various input and operational errors.

• Retry Logic: Implements automatic retries for transient failures, improving system resilience during interruptions.

---

Chroma MCP Server

A Model Context Protocol (MCP) server implementation providing 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
  Errors: 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
  Errors: 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 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, 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

Common error messages:

• 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 MCP Inspector for interactive testing:

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

Use the 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.