Chroma

What is Chroma MCP Server?

Chroma MCP Server is an implementation of the Model Context Protocol (MCP) that provides vector database capabilities using Chroma. It enables semantic document search, metadata filtering, and document management with persistent storage.

How to use Chroma MCP Server?

Installation:

1. Install dependencies:

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

Configuration (Claude Desktop):

Add the server configuration to your Claude Desktop config file:

• 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"
      ]
    }
  }
}

Usage:

1. Start the server:

   uv run chroma
   

2. Interact with the server using MCP tools (e.g., Python):

   # 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"
       }
   })
   

Key Features of Chroma MCP Server

• 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 a local directory (src/chroma/data) between server restarts.
• Error Handling: Comprehensive error handling with clear messages.
• Retry Logic: Automatic retries for transient failures.
• Document Management: CRUD operations for documents (create_document, read_document, update_document, delete_document, list_documents).
• Search Operations: search_similar for finding semantically similar documents.

Use Cases of Chroma MCP Server

• Building applications requiring semantic search capabilities.
• Managing and retrieving documents based on content and metadata.
• Integrating vector database functionality into MCP-compatible systems.
• Creating knowledge bases with intelligent search.

FAQ about Chroma MCP Server

Q: What are the system requirements for Chroma MCP Server? A: Python 3.8+, Chroma 0.4.0+, and MCP SDK 0.1.0+.

Q: Where does Chroma MCP Server store its data? A: Data is stored persistently in the src/chroma/data directory.

Q: How can I test Chroma MCP Server? A: You can use the MCP Inspector for interactive testing. Run npx @modelcontextprotocol/inspector uv --directory C:/MCP/server/community/chroma run chroma and use its web interface to test functionalities.

Q: What kind of errors can I expect from Chroma MCP Server? A: The server provides clear error messages for common scenarios such as Document already exists, Document not found, Invalid input, and Invalid filter.

Q: How can I contribute to Chroma MCP Server? A: Contributions are welcome. Please refer to the CONTRIBUTING.md file for guidelines on code style, testing requirements, and the pull request process.

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.