repository·main·Indexed 20 days ago
https://github.com/chroma-core/chroma-mcpA Model Context Protocol (MCP) implementation that integrates the Chroma embedding database with LLM applications. It provides tools for collection management, document operations, and semantic or full-text search. The server supports multiple deployment modes, including ephemeral (in-memory), persistent (file-based), self-hosted HTTP, and Chroma Cloud, and integrates with embedding functions from providers such as OpenAI, Cohere, Jina, VoyageAI, and Roboflow.
Chroma MCP supports the following embedding functions:
defaultcohereopenaijinavoyageairoboflowEmbedding functions are persisted as part of the collection configuration. Once a collection is created with a specific function, that function is automatically used for all subsequent queries and inserts. For functions requiring external APIs, you must provide the appropriate API key via environment variables using the pattern CHROMA_<PROVIDER>_API_KEY (e.g., CHROMA_COHERE_API_KEY).
To use Chroma MCP with Claude Desktop, add a configuration entry to your claude_desktop_config.json file. Choose the configuration that matches your desired client type.
# Ephemeral Client (In-memory)
"chroma": {
"command": "uvx",
"args": [
"chroma-mcp"
]
}
# Persistent Client (File-based)
"chroma": {
"command": "uvx",
"args": [
"chroma-mcp",
"--client-type",
"persistent",
"--data-dir",
"/full/path/to/your/data/directory"
]
}
# Chroma Cloud Client
"chroma": {
"command": "uvx",
"args": [
"chroma-mcp",
"--client-type",
"cloud",
"--tenant",
"your-tenant-id",
"--database",
"your-database-name",
"--api-key",
"your-api-key"
]
}
# Self-hosted HTTP Client
"chroma": {
"command": "uvx",
"args": [
"chroma-mcp",
"--client-type",
"http",
"--host",
"your-host",
"--port",
"your-port",
"--custom-auth-credentials",
"your-custom-auth-credentials",
"--ssl",
"true"
]
}The server loads configuration from system environment variables or a .env file. If using a .env file, specify its location using the CHROMA_DOTENV_PATH environment variable or the --dotenv-path CLI flag. Command-line arguments take precedence over environment variables.
Common Variables:
CHROMA_CLIENT_TYPE: Set to http, cloud, persistent, or ephemeral.Persistent Client:
CHROMA_DATA_DIR: Path to the data directory.Cloud Client:
CHROMA_TENANT: Your tenant ID.CHROMA_DATABASE: Your database name.CHROMA_API_KEY: Your API key.HTTP Client:
CHROMA_HOST: Host address.CHROMA_PORT: Port number.CHROMA_CUSTOM_AUTH_CREDENTIALS: Custom authentication credentials.CHROMA_SSL: Set to true for SSL.Embedding API Keys:
Use the format CHROMA_<PROVIDER>_API_KEY. Example: CHROMA_COHERE_API_KEY="<key>".
# Example setup for a persistent client using environment variables
export CHROMA_CLIENT_TYPE="persistent"
export CHROMA_DATA_DIR="/full/path/to/your/data/directory"
export CHROMA_DOTENV_PATH="/path/to/your/.env"The Chroma MCP server supports four different client connection types. You can specify the type using the --client-type flag or the CHROMA_CLIENT_TYPE environment variable.
Supported types:
ephemeral: An in-memory client (default).persistent: Uses a local directory for data storage. Requires --data-dir or CHROMA_DATA_DIR.http: Connects to a self-hosted Chroma instance. Requires --host or CHROMA_HOST.cloud: Connects to Chroma Cloud. Requires --tenant, --database, and --api-key (or their corresponding environment variables).# Example: Running with a persistent client
python -m chroma_mcp.server --client-type persistent --data-dir ./chroma_data
# Example: Running with an HTTP client
python -m chroma_mcp.server --client-type http --host localhost --port 8000The server exposes the following tools for collection and document management:
Collection Management:
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.Document Operations:
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.chroma_query_documents(collection_name, query_texts, n_results, where, where_document, include)
Performs a semantic search.
query_texts: List of strings to search for.where: Metadata filters (e.g., {"field": "value"} or {"field": {"$gt": 5}}).where_document: Document content filters (e.g., {"$contains": "value"} or {"$regex": "[a-z]+"}).include: Fields to return (default: ["documents", "metadatas", "distances"]).chroma_get_documents(collection_name, ids, where, where_document, include, limit, offset)
Retrieves documents based on specific IDs or filters without semantic similarity.
ids: Optional list of specific IDs to fetch.limit/offset: Pagination parameters.Use these tools to manage document content within a collection:
chroma_add_documents(collection_name, documents, ids, metadatas)
documents: List of text strings.ids: List of unique identifiers (required, cannot be empty strings).metadatas: Optional list of metadata dictionaries.ValueError if IDs already exist in the collection. Use chroma_update_documents for existing IDs.chroma_update_documents(collection_name, ids, embeddings, metadatas, documents)
ids: List of IDs to update (required).embeddings, metadatas, or documents.ids.chroma_peek_collection(collection_name, limit) to quickly inspect a small sample of documents within a collection. By default, it returns the first 5 documents.The chroma_mcp package exposes a main function which serves as the entrypoint for starting the Chroma Model Context Protocol (MCP) server. This function initializes the server and its associated tools, allowing it to be used as a module or called directly in a script to provide Chroma's vector database capabilities to MCP-compatible clients.
from chroma_mcp import main
if __name__ == "__main__":
main()chroma_delete_documents(collection_name, ids) to remove specific documents from a collection using their IDs. Non-existent IDs are ignored by the operation.The server provides several tools to manage the lifecycle and metadata of collections:
chroma_list_collections(limit, offset): Returns a list of collection names. Returns ["__NO_COLLECTIONS_FOUND__"] if empty.chroma_create_collection(collection_name, embedding_function_name, metadata): Creates a new collection. Supported embedding_function_name values: 'default', 'cohere', 'openai', 'jina', 'voyageai', 'roboflow'.chroma_get_collection_info(collection_name): Returns a dictionary containing the collection name, document count, and a sample of 3 documents.chroma_get_collection_count(collection_name): Returns the integer count of documents.chroma_modify_collection(collection_name, new_name, new_metadata): Updates the name or metadata of an existing collection.chroma_fork_collection(collection_name, new_collection_name): Creates a new collection as a fork of an existing one.chroma_delete_collection(collection_name): Deletes the specified collection.