Chroma MCP Server

Chroma MCP Server

codecov

PyPI - Version

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

Motivation: AI Development Working Memory

In AI-assisted development workflows, particularly when using tools like Cursor or GitHub Copilot over multiple sessions, maintaining context from previous interactions is crucial but often manual. Developers frequently resort to creating temporary markdown files or other artifacts simply to capture and reload context into a new chat session.

The Chroma MCP Server aims to streamline this process by providing a persistent, searchable "working memory":

• Automated Context Recall: Instead of manual context loading, AI assistants (guided by specific rules or instructions) can query this MCP server to retrieve relevant information from past sessions based on the current development task.
• Developer-Managed Persistence: Developers can actively summarize key decisions, code snippets, or insights from the current session and store them in ChromaDB via the MCP interface. This allows building a rich, task-relevant knowledge base over time.
• Separation of Concerns: This "working memory" is distinct from final user-facing documentation or committed code artifacts, focusing specifically on capturing the transient but valuable context of the development process itself.

By integrating ChromaDB through MCP, this server facilitates more seamless and context-aware AI-assisted development, reducing manual overhead and improving the continuity of complex tasks across multiple sessions.

Overview

The Chroma MCP Server allows you to connect AI applications with Chroma through the Model Context Protocol. This enables AI models to:

• Store and retrieve embeddings
• Perform semantic search on vector data
• Manage collections of embeddings
• Support RAG (Retrieval Augmented Generation) workflows

See the API Reference for a detailed list of available tools and their parameters.

Installation

Choose your preferred installation method:

Standard Installation

# Using pip
pip install chroma-mcp-server

# Using UVX (recommended for Cursor)
uv pip install chroma-mcp-server

Full Installation (with embedding models)

# Using pip
pip install chroma-mcp-server[full]

# Using UVX
uv pip install "chroma-mcp-server[full]"

Usage

Starting the server

# Using the command-line executable
chroma-mcp-server

# Or using the Python module
python -m chroma_mcp.server

Checking the Version

chroma-mcp-server --version

Configuration

The server can be configured with command-line options or environment variables:

Command-line Options

chroma-mcp-server --client-type persistent --data-dir ./my_data --log-dir ./logs --embedding-function accurate

Environment Variables

export CHROMA_CLIENT_TYPE=persistent
export CHROMA_DATA_DIR=./my_data
export CHROMA_LOG_DIR=./logs
export CHROMA_EMBEDDING_FUNCTION=accurate
chroma-mcp-server

Available Configuration Options

• --client-type: Type of Chroma client (ephemeral, persistent, http, cloud)
• --data-dir: Path to data directory for persistent client
• --log-dir: Path to log directory
• --host: Host address for HTTP client
• --port: Port for HTTP client
• --ssl: Whether to use SSL for HTTP client
• --tenant: Tenant ID for Cloud client
• --database: Database name for Cloud client
• --api-key: API key for Cloud client
• --cpu-execution-provider: Force CPU execution provider for local embedding functions (auto, true, false)
• --embedding-function: Name of the embedding function to use. Choices: 'default'/'fast' (Local CPU, balanced), 'accurate' (Local CPU/GPU via sentence-transformers, higher accuracy), 'openai' (API, general purpose), 'cohere' (API, retrieval/multilingual focus), 'huggingface' (API, flexible model choice), 'jina' (API, long context focus), 'voyageai' (API, retrieval focus), 'gemini' (API, general purpose). API-based functions require corresponding API keys set as environment variables (e.g., OPENAI_API_KEY).

See Getting Started for more setup details.

Cursor Integration

To use with Cursor, add the following to your .cursor/mcp.json:

{
  "mcpServers": {
    "chroma": {
      "command": "uvx",
      "args": [
        "chroma-mcp-server",
        "--embedding-function=default" // Example: Choose your desired embedding function
      ],
      "env": {
        "CHROMA_CLIENT_TYPE": "persistent",
        "CHROMA_DATA_DIR": "/path/to/data/dir", // Replace with your actual path
        "CHROMA_LOG_DIR": "/path/to/logs/dir",   // Replace with your actual path
        "LOG_LEVEL": "INFO",
        "MCP_LOG_LEVEL": "INFO",
        // Add API keys here if using API-based embedding functions
        // "OPENAI_API_KEY": "your_openai_key",
        // "GOOGLE_API_KEY": "your_google_key"
      }
    }
  }
}

See Cursor Integration for more details.

Development

For instructions on how to set up the development environment, run tests, build the package, and contribute, please see the Developer Guide.

Working Memory and Thinking Tools

This server includes specialized tools for creating a persistent, searchable "working memory" to aid AI development workflows. Learn more about how these tools leverage embeddings to manage context across sessions in the Embeddings and Thinking Tools Guide.

Testing the Tools

A simulated workflow using the MCP tools is available in the MCP Test Flow document.

License

MIT License (see LICENSE)