# chroma-core/chroma-mcp [Health: Active]
**Category:** 🗄️ Databases
**Repository:** https://github.com/chroma-core/chroma-mcp
**GitHub Stars:** 591
**Views:** 2
**Installs:** 0
**Upvotes:** 0
**Directory Page:** https://allmcps.com/mcp/chroma-core-chroma-mcp
## Description
Chroma MCP server to access local and cloud Chroma instances for retrieval capabilities
## Tools
Capabilities this server exposes over MCP:
- **chroma_list_collections** — List all collection names in the Chroma database with pagination support.
Args:
limit: Optional maximum number of collections to return
offset: Optional number of collections to skip before returning results
Returns:
List of collection names or ["__NO_COLLECTIONS_FOUND__"] if database is empty
- **chroma_create_collection** — Create a new Chroma collection with configurable HNSW parameters.
Args:
collection_name: Name of the collection to create
embedding_function_name: Name of the embedding function to use. Options: 'default', 'cohere', 'openai', 'jina', 'voyageai', 'ollama', 'roboflow'
metadata: Optional metadata dict to add to the collection
- **chroma_peek_collection** — Peek at documents in a Chroma collection.
Args:
collection_name: Name of the collection to peek into
limit: Number of documents to peek at
- **chroma_get_collection_info** — Get information about a Chroma collection.
Args:
collection_name: Name of the collection to get info about
- **chroma_get_collection_count** — Get the number of documents in a Chroma collection.
Args:
collection_name: Name of the collection to count
- **chroma_modify_collection** — Modify a Chroma collection's name or metadata.
Args:
collection_name: Name of the collection to modify
new_name: Optional new name for the collection
new_metadata: Optional new metadata for the collection
- **chroma_fork_collection** — Fork a Chroma collection.
Args:
collection_name: Name of the collection to fork
new_collection_name: Name of the new collection to create
metadata: Optional metadata dict to add to the new collection
- **chroma_delete_collection** — Delete a Chroma collection.
Args:
collection_name: Name of the collection to delete
- **chroma_add_documents** — Add documents to a Chroma collection.
Args:
collection_name: Name of the collection to add documents to
documents: List of text documents to add
ids: List of IDs for the documents (required)
metadatas: Optional list of metadata dictionaries for each document
- **chroma_query_documents** — Query documents from a Chroma collection with advanced filtering.
Args:
collection_name: Name of the collection to query
query_texts: List of query texts to search for
n_results: Number of results to return per query
where: Optional metadata filters using Chroma's query operators
Examples:
- Simple equality: {"metadata_field": "value"}
- Comparison: {"metadata_field": {"$gt": 5}}
- Logical AND: {"$and": [{"field1": {"$eq": "value1"}}, {"field2": {"$gt": 5}}]}
- Logical OR: {"$or": [{"field1": {"$eq": "value1"}}, {"field1": {"$eq": "value2"}}]}
where_document: Optional document content filters
Examples:
- Contains: {"$contains": "value"}
- Not contains: {"$not_contains": "value"}
- Regex: {"$regex": "[a-z]+"}
- Not regex: {"$not_regex": "[a-z]+"}
- Logical AND: {"$and": [{"$contains": "value1"}, {"$not_regex": "[a-z]+"}]}
- Logical OR: {"$or": [{"$regex": "[a-z]+"}, {"$not_contains": "value2"}]}
include: List of what to include in response. By default, this will include documents, metadatas, and distances.
- **chroma_get_documents** — Get documents from a Chroma collection with optional filtering.
Args:
collection_name: Name of the collection to get documents from
ids: Optional list of document IDs to retrieve
where: Optional metadata filters using Chroma's query operators
Examples:
- Simple equality: {"metadata_field": "value"}
- Comparison: {"metadata_field": {"$gt": 5}}
- Logical AND: {"$and": [{"field1": {"$eq": "value1"}}, {"field2": {"$gt": 5}}]}
- Logical OR: {"$or": [{"field1": {"$eq": "value1"}}, {"field1": {"$eq": "value2"}}]}
where_document: Optional document content filters
Examples:
- Contains: {"$contains": "value"}
- Not contains: {"$not_contains": "value"}
- Regex: {"$regex": "[a-z]+"}
- Not regex: {"$not_regex": "[a-z]+"}
- Logical AND: {"$and": [{"$contains": "value1"}, {"$not_regex": "[a-z]+"}]}
- Logical OR: {"$or": [{"$regex": "[a-z]+"}, {"$not_contains": "value2"}]}
include: List of what to include in response. By default, this will include documents, and metadatas.
limit: Optional maximum number of documents to return
offset: Optional number of documents to skip before returning results
Returns:
Dictionary containing the matching documents, their IDs, and requested includes
- **chroma_update_documents** — Update documents in a Chroma collection.
Args:
collection_name: Name of the collection to update documents in
ids: List of document IDs to update (required)
embeddings: Optional list of new embeddings for the documents.
Must match length of ids if provided.
metadatas: Optional list of new metadata dictionaries for the documents.
Must match length of ids if provided.
documents: Optional list of new text documents.
Must match length of ids if provided.
Returns:
A confirmation message indicating the number of documents updated.
Raises:
ValueError: If 'ids' is empty or if none of 'embeddings', 'metadatas',
or 'documents' are provided, or if the length of provided
update lists does not match the length of 'ids'.
Exception: If the collection does not exist or if the update operation fails.
- **chroma_delete_documents** — Delete documents from a Chroma collection.
Args:
collection_name: Name of the collection to delete documents from
ids: List of document IDs to delete
Returns:
A confirmation message indicating the number of documents deleted.
Raises:
ValueError: If 'ids' is empty
Exception: If the collection does not exist or if the delete operation fails.
## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):
```json
"mcpServers": {
"chroma-mcp": {
"command": "uvx",
"args": ["chroma-mcp"],
"env": {
"COHERE_API_KEY": "",
"OPENAI_API_KEY": "",
"JINA_API_KEY": "",
"VOYAGEAI_API_KEY": "",
"ROBOFLOW_API_KEY": ""
}
}
}
```
**Requires environment variables:** `COHERE_API_KEY`, `OPENAI_API_KEY`, `JINA_API_KEY`, `VOYAGEAI_API_KEY`, `ROBOFLOW_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).
## Documentation & README
Chroma - the open-source embedding database.
The fastest way to build Python or JavaScript LLM apps with memory!
|
|
Docs
|
Homepage
# Chroma MCP Server
[](https://smithery.ai/server/@chroma-core/chroma-mcp)
[The Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol designed for effortless integration between LLM applications and external data sources or tools, offering a standardized framework to seamlessly provide LLMs with the context they require.
This server provides data retrieval capabilities powered by Chroma, enabling AI models to create collections over generated data and user inputs, and retrieve that data using vector search, full text search, metadata filtering, and more.
This is a MCP server for self-hosting your access to Chroma. If you are looking for [Package Search](https://www.trychroma.com/package-search) you can find the repository for that [here](https://github.com/chroma-core/package-search).
## Features
- **Flexible Client Types**
- Ephemeral (in-memory) for testing and development
- Persistent for file-based storage
- HTTP client for self-hosted Chroma instances
- Cloud client for Chroma Cloud integration (automatically connects to api.trychroma.com)
- **Collection Management**
- Create, modify, and delete collections
- List all collections with pagination support
- Get collection information and statistics
- Configure HNSW parameters for optimized vector search
- Select embedding functions when creating collections
- **Document Operations**
- Add documents with optional metadata and custom IDs
- Query documents using semantic search
- Advanced filtering using metadata and document content
- Retrieve documents by IDs or filters
- Full text search capabilities
### Supported Tools
- `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 several embedding functions: `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 persistance 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](#embedding-function-environment-variables)
## Usage with Claude Desktop
1. To add an ephemeral client, add the following to your `claude_desktop_config.json` file:
```json
"chroma": {
"command": "uvx",
"args": [
"chroma-mcp"
]
}
```
2. To add a persistent client, add the following to your `claude_desktop_config.json` file:
```json
"chroma": {
"command": "uvx",
"args": [
"chroma-mcp",
"--client-type",
"persistent",
"--data-dir",
"/full/path/to/your/data/directory"
]
}
```
This will create a persistent client that will use the data directory specified.
3. To connect to Chroma Cloud, add the following to your `claude_desktop_config.json` file:
```json
"chroma": {
"command": "uvx",
"args": [
"chroma-mcp",
"--client-type",
"cloud",
"--tenant",
"your-tenant-id",
"--database",
"your-database-name",
"--api-key",
"your-api-key"
]
}
```
This will create a cloud client that automatically connects to api.trychroma.com using SSL.
**Note:** Adding API keys in arguments is fine on local devices, but for safety, you can also specify a custom path for your environment configuration file using the `--dotenv-path` argument within the `args` list, for example: `"args": ["chroma-mcp", "--dotenv-path", "/custom/path/.env"]`.
4. To connect to a [self-hosted Chroma instance on your own cloud provider](https://docs.trychroma.com/
production/deployment), add the following to your `claude_desktop_config.json` file:
```json
"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 will create an HTTP client that connects to your self-hosted Chroma instance.
### Demos
Find reference usages, such as shared knowledge bases & adding memory to context windows in the [Chroma MCP Docs](https://docs.trychroma.com/integrations/frameworks/anthropic-mcp#using-chroma-with-claude)
### Using Environment Variables
You can also use environment variables to configure the client. The server will automatically load variables from a `.env` file located at the path specified by `--dotenv-path` (defaults to `.chroma_env` in the working directory) or from system environment variables. Command-line arguments take precedence over environment variables.
```bash
# 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 access an API key, follow the naming convention
`CHROMA_<>_API_KEY=""`.
So to set a Cohere API key, set the environment variable `CHROMA_COHERE_API_KEY=""`. We recommend adding this to a .env file somewhere and using the `CHROMA_DOTENV_PATH` environment variable or `--dotenv-path` flag to set that location for safekeeping.