Chroma MCP Server

A Model Context Protocol (MCP) server integration for Chroma, the open-source embedding database.

Overview

Chroma MCP Server creates a persistent, searchable "working memory" for AI-assisted development:

Automated Context Recall: AI assistants can query relevant information from past sessions
Developer-Managed Persistence: Store key decisions and insights in ChromaDB via MCP
Second Brain Integration: Integrates with IDE workflows to create a unified knowledge hub

Key features:

Automated Codebase Indexing: Track and index code changes
Automated Chat Logging: Log AI interactions with enhanced context capture (code diffs, tool sequences)
Bidirectional Linking: Connect discussions to code changes for tracing feature evolution
Semantic Code Chunking: Preserve logical code structures for more meaningful context retrieval
Working Memory Tools: MCP commands for capturing and retrieving development context
Validation System: Evidence-based validation for code changes and learning promotions
Automated Test-Driven Learning: Fully automated workflow from test failure to verified fix and learning promotion. See the Pytest Plugin Usage Guide to integrate this into your projects.

See the Getting Started with your Second Brain guide for more details.

Quick Start

Installation

# Basic installation
pip install chroma-mcp-server

# Full installation with all embedding models
pip install "chroma-mcp-server[full]"

Running

# With in-memory storage (data lost on restart)
chroma-mcp-server --client-type ephemeral

# With persistent storage
chroma-mcp-server --client-type persistent --data-dir ./my_data

Cursor Integration

Add or modify .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "chroma": {
      "command": "uvx",
      "args": [
        "chroma-mcp-server"
      ],
      "env": {
        "CHROMA_CLIENT_TYPE": "persistent",
        "CHROMA_DATA_DIR": "/path/to/your/data",
        "CHROMA_LOG_DIR": "/path/to/your/logs",
        "LOG_LEVEL": "INFO",
        "MCP_LOG_LEVEL": "INFO",
        "MCP_SERVER_LOG_LEVEL": "INFO"
      }
    }
  }
}

Recent Improvements

Enhanced Context Capture: Automatically extracts code diffs, tool sequences, and assigns confidence scores
Bidirectional Linking: Creates navigable connections between chat discussions and code changes
Semantic Code Chunking: Uses logical boundaries (functions, classes) instead of fixed-size chunks
Server-Side Timestamp Enforcement: Ensures consistent timestamps across all collections
Automatic Collection Creation: Essential collections (e.g., chat_history_v1, codebase_v1) are automatically created on server startup if they don't exist.
Enhanced Logging System: Per-execution log files prevent contamination of JSON communication in stdio mode
Embedding Function Management: Tools to update collection metadata when changing embedding functions
Collection Setup Command: Simplifies creation of multiple collections with consistent configuration
Auto-Promote Workflow: Streamlined derived learning promotion with automatic handling of high-confidence entries
Smart Defaults: Interactive promotion with intelligent defaults for all fields based on context
Low Confidence Warnings: Visual indicators for entries that may need more careful review
Automated Test Workflow: Fully automated capture of test failures, monitoring for fixes, and validated learning promotion

Documentation

Comprehensive documentation is available in the docs directory:

Main Documentation - Complete guide to installation, configuration, and usage
Getting Started - Detailed setup instructions
Developer Guide - For contributors and developers
IDE & Tool Integration Guides - Guides for integrating with IDEs and other tools.
Automated Chat Logging - Enriched chat history with bidirectional linking
Usage Guides - Detailed guides on how to use specific features and workflows.
Enhanced Context Capture - Details on code diff extraction and tool sequencing
Semantic Code Chunking - Logic-preserving code chunking for meaningful retrieval
Automated Test Workflow (Pytest Plugin Usage) - Test-driven learning with automatic validation
Thinking Tools & Utilities - Documentation for structured thinking and memory tools.
Client and Developer Scripts - Guides for CLI tools and developer scripts.
Logging Documentation - Overview of logging features and configuration.
Server Logging - Details on the improved logging system
Automation Documentation - Guides on automating development tasks.
Project Rules & Guidelines - Development rules, guidelines, and best practices.
Refactoring Plans - Documentation on various refactoring efforts and architectural plans.
API Reference - Available MCP tools and parameters

License

Chroma MCP Server is licensed under the MIT License with Commons Clause. This means you can:

✅ Allowed:

Use Chroma MCP Server for any purpose (personal, commercial, academic)
Modify the code
Distribute copies
Create and sell products built using Chroma MCP Server

❌ Not Allowed:

Sell Chroma MCP Server itself
Offer Chroma MCP Server as a hosted service
Create competing products based on Chroma MCP Server

See the LICENSE.md file for the complete license text.

Metadata

Release files for chroma-mcp-server 0.2.28

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for chroma-mcp-server 0.2.28
File	Size	Uploaded
chroma_mcp_server-0.2.28.tar.gz	513.9 kB	May 29, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for chroma-mcp-server 0.2.28
File	Interpreter	ABI	Platform	Reset
chroma_mcp_server-0.2.28-py3-none-any.whl 158.2 kB May 29, 2025	Python 3	none	any	Details

Total release size: 672.1 kB

Release files / chroma_mcp_server-0.2.28.tar.gz

Download URL	chroma_mcp_server-0.2.28.tar.gz
Size	513.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`d5e55f2e891fc0009ddec1bbff3c8d917745d55aab9d3609a556032eb376df8f`
BLAKE2b-256 checksum How to use checksums	`de5ced0f901e041856753a68272e3c7ae86008ab7f527f55818d825304cd891b`
Upload date	May 29, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`python-httpx/0.28.1`

Release files / chroma_mcp_server-0.2.28-py3-none-any.whl

Download URL	chroma_mcp_server-0.2.28-py3-none-any.whl
Size	158.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`0b0f743f0f3c7a4ab715e805772b2b184639bf4ff8937ce0dd07322002b600a7`
BLAKE2b-256 checksum How to use checksums	`cdbcbc60d8298cbc613d2e4e7cb6a0674d1f16eb59b4947ba5e6366411e5f60c`
Upload date	May 29, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`python-httpx/0.28.1`