Content
# Chroma MCP Server
[](https://github.com/djm81/chroma_mcp_server/actions/workflows/tests.yml)
[](https://codecov.io/gh/djm81/chroma_mcp_server)
[](https://pypi.org/project/chroma-mcp-server)
A Model Context Protocol (MCP) server integration for [Chroma](https://www.trychroma.com/), 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](docs/integration/pytest_plugin_usage.md) to integrate this into your projects.
See the [Getting Started with your Second Brain guide](docs/getting_started_second_brain.md) for more details.
## Quick Start
### Installation
```bash
# Basic installation
pip install chroma-mcp-server
# Full installation with all embedding models
pip install "chroma-mcp-server[full]"
```
### Running
```bash
# 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:
```json
{
"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](docs/):
- [Main Documentation](docs/README.md) - Complete guide to installation, configuration, and usage
- [Getting Started](docs/getting_started.md) - Detailed setup instructions
- [Developer Guide](docs/developer_guide.md) - For contributors and developers
- [IDE & Tool Integration Guides](docs/integration/README.md) - Guides for integrating with IDEs and other tools.
- [Automated Chat Logging](docs/integration/automated_chat_logging.md) - Enriched chat history with bidirectional linking
- [Usage Guides](docs/usage/README.md) - Detailed guides on how to use specific features and workflows.
- [Enhanced Context Capture](docs/usage/enhanced_context_capture.md) - Details on code diff extraction and tool sequencing
- [Semantic Code Chunking](docs/usage/semantic_chunking.md) - Logic-preserving code chunking for meaningful retrieval
- [Automated Test Workflow (Pytest Plugin Usage)](docs/integration/pytest_plugin_usage.md) - Test-driven learning with automatic validation
- [Thinking Tools & Utilities](docs/thinking_tools/README.md) - Documentation for structured thinking and memory tools.
- [Client and Developer Scripts](docs/scripts/README.md) - Guides for CLI tools and developer scripts.
- [Logging Documentation](docs/logging/README.md) - Overview of logging features and configuration.
- [Server Logging](docs/logging/server_logging.md) - Details on the improved logging system
- [Automation Documentation](docs/automation/README.md) - Guides on automating development tasks.
- [Project Rules & Guidelines](docs/rules/README.md) - Development rules, guidelines, and best practices.
- [Refactoring Plans](docs/refactoring/README.md) - Documentation on various refactoring efforts and architectural plans.
- [API Reference](docs/api_reference.md) - 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](LICENSE.md) file for the complete license text.
