Chroma MCP Server: Seamlessly Integrate LLMs with Context

Unlock the power of Large Language Models (LLMs) by connecting them to the data they need with the Chroma MCP Server. This server implements the Model Context Protocol (MCP), an open standard that streamlines the integration of LLMs with external data sources and tools. Empower your AI-powered applications with context-aware capabilities, whether you're building intelligent IDEs, enhancing chat interfaces, or creating custom AI workflows.

This server leverages Chroma, the open-source embedding database, to provide robust data retrieval capabilities. AI models can create collections over generated data and user inputs, then retrieve that data using a powerful combination of vector search, full-text search, and metadata filtering.

Key Features

• Flexible Client Types: Choose the client that best suits your needs:

  • Ephemeral (in-memory): Ideal for rapid prototyping and development.
  • Persistent: Utilizes file-based storage for data persistence.
  • HTTP: Connect to self-hosted Chroma instances for production deployments.
  • Cloud: Seamlessly integrates with Chroma Cloud (automatically connects to api.trychroma.com).

• Comprehensive Collection Management:

  • Create, modify, and delete collections with ease.
  • List all collections with pagination support for efficient management.
  • Retrieve detailed collection information and statistics.
  • Configure HNSW parameters to optimize vector search performance.
  • Select from a variety of embedding functions when creating collections.

• Powerful Document Operations:

  • Add documents with optional metadata and custom IDs.
  • Query documents using semantic search for contextually relevant results.
  • Leverage advanced filtering using metadata and document content.
  • Retrieve documents by IDs or filters with pagination.
  • Utilize full-text search capabilities for comprehensive information retrieval.

Supported Tools

The Chroma MCP Server exposes a rich set of tools for interacting with your data:

• chroma_list_collections: List all collections with pagination support.
• chroma_create_collection: Create a new collection with optional HNSW configuration.
• chroma_peek_collection: View a sample of documents in a collection.
• chroma_get_collection_info: Get detailed information about a collection.
• chroma_get_collection_count: Get the number of documents in a collection.
• chroma_modify_collection: Update a collection's name or metadata.
• chroma_delete_collection: Delete a collection.
• chroma_add_documents: Add documents with optional metadata and custom IDs.
• chroma_query_documents: Query documents using semantic search with advanced filtering.
• chroma_get_documents: Retrieve documents by IDs or filters with pagination.
• chroma_update_documents: Update existing documents' content, metadata, or embeddings.
• chroma_delete_documents: Delete specific documents from a collection.

Embedding Functions

Chroma MCP supports a variety of embedding functions, including: default, cohere, openai, jina, voyageai, and roboflow.

The embedding functions utilize Chroma's collection configuration, which persists the selected embedding function of a collection for retrieval. Once a collection is created using the collection configuration, on retrieval for future queries and inserts, the same embedding function will be used, without needing to specify the embedding function again. Embedding function persistence was added in v1.0.0 of Chroma, so if you created a collection using version <=0.6.3, this feature is not supported.

When accessing embedding functions that utilize external APIs, please be sure to add the environment variable for the API key with the correct format, found in Embedding Function Environment Variables

Integration with Claude Desktop

The Chroma MCP Server seamlessly integrates with Claude Desktop. Here's how to configure it:

1. Ephemeral Client: Add the following to your claude_desktop_config.json file:

   "chroma": {
       "command": "uvx",
       "args": [
           "chroma-mcp"
       ]
   }

2. Persistent Client: Add the following to your claude_desktop_config.json file:

   "chroma": {
       "command": "uvx",
       "args": [
           "chroma-mcp",
           "--client-type",
           "persistent",
           "--data-dir",
           "/full/path/to/your/data/directory"
       ]
   }

   This creates a persistent client that uses the specified data directory.

3. Chroma Cloud Client: Add the following to your claude_desktop_config.json file:

   "chroma": {
       "command": "uvx",
       "args": [
           "chroma-mcp",
           "--client-type",
           "cloud",
           "--tenant",
           "your-tenant-id",
           "--database",
           "your-database-name",
           "--api-key",
           "your-api-key"
       ]
   }

   This creates a cloud client that automatically connects to api.trychroma.com using SSL.

   Security Note: While adding API keys in arguments is acceptable for local development, consider using a custom environment configuration file for production environments. Specify the path to your .env file using the --dotenv-path argument within the args list: "args": ["chroma-mcp", "--dotenv-path", "/custom/path/.env"].

4. Self-Hosted Chroma Instance: To connect to a self-hosted Chroma instance on your own cloud provider, add the following to your claude_desktop_config.json file:

   "chroma": {
       "command": "uvx",
       "args": [
         "chroma-mcp",
         "--client-type",
         "http",
         "--host",
         "your-host",
         "--port",
         "your-port",
         "--custom-auth-credentials",
         "your-custom-auth-credentials",
         "--ssl",
         "true"
       ]
   }

   This creates an HTTP client that connects to your self-hosted Chroma instance.

Demos

Explore practical use cases, such as shared knowledge bases and adding memory to context windows, in the Chroma MCP Docs.

Configuring with Environment Variables

You can also configure the client using environment variables. The server automatically loads variables from a .env file (default: .chroma_env in the working directory) or from system environment variables. Command-line arguments take precedence.

# Common variables
export CHROMA_CLIENT_TYPE="http"  # or "cloud", "persistent", "ephemeral"

# For persistent client
export CHROMA_DATA_DIR="/full/path/to/your/data/directory"

# For cloud client (Chroma Cloud)
export CHROMA_TENANT="your-tenant-id"
export CHROMA_DATABASE="your-database-name"
export CHROMA_API_KEY="your-api-key"

# For HTTP client (self-hosted)
export CHROMA_HOST="your-host"
export CHROMA_PORT="your-port"
export CHROMA_CUSTOM_AUTH_CREDENTIALS="your-custom-auth-credentials"
export CHROMA_SSL="true"

# Optional: Specify path to .env file (defaults to .chroma_env)
export CHROMA_DOTENV_PATH="/path/to/your/.env"

Embedding Function Environment Variables

When using external embedding functions that require an API key, use the naming convention CHROMA_<EMBEDDING_FUNCTION>_API_KEY="<key>". For example, to set a Cohere API key, set the environment variable CHROMA_COHERE_API_KEY="<your_cohere_api_key>". We recommend storing these keys in a .env file and using the CHROMA_DOTENV_PATH environment variable or --dotenv-path flag to specify its location for enhanced security.