Usage with Claude Desktop
- To add an ephemeral client, add the following to your
claude_desktop_config.json file:
"chroma": {
"command": "uvx",
"args": [
"chroma-mcp"
]
}
- To add a 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 will create a persistent client that will use the data directory specified.
- To connect to Chroma Cloud, 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 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"].
- 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:
"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
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.
# 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="<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.