Chroma MCP Server

1<p align="center">
2  <a href="https://trychroma.com"><img src="https://user-images.githubusercontent.com/891664/227103090-6624bf7d-9524-4e05-9d2c-c28d5d451481.png" alt="Chroma logo"></a>
3</p>
4 
5<p align="center">
6    <b>Chroma - the open-source embedding database</b>. <br />
7    The fastest way to build Python or JavaScript LLM apps with memory!
8</p>
9 
10<p align="center">
11  <a href="https://discord.gg/MMeYNTmh3x" target="_blank">
12      <img src="https://img.shields.io/discord/1073293645303795742?cacheSeconds=3600" alt="Discord">
13  </a> |
14  <a href="https://github.com/chroma-core/chroma/blob/master/LICENSE" target="_blank">
15      <img src="https://img.shields.io/static/v1?label=license&message=Apache 2.0&color=white" alt="License">
16  </a> |
17  <a href="https://docs.trychroma.com/" target="_blank">
18      Docs
19  </a> |
20  <a href="https://www.trychroma.com/" target="_blank">
21      Homepage
22  </a>
23</p>
24 
25# Chroma MCP Server
26 
27[![smithery badge](https://smithery.ai/badge/@chroma-core/chroma-mcp)](https://smithery.ai/server/@chroma-core/chroma-mcp)
28 
29[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.
30 
31This 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.
32 
33This 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).
34 
35## Features
36 
37- **Flexible Client Types**
38  - Ephemeral (in-memory) for testing and development
39  - Persistent for file-based storage
40  - HTTP client for self-hosted Chroma instances
41  - Cloud client for Chroma Cloud integration (automatically connects to api.trychroma.com)
42 
43- **Collection Management**
44  - Create, modify, and delete collections
45  - List all collections with pagination support
46  - Get collection information and statistics
47  - Configure HNSW parameters for optimized vector search
48  - Select embedding functions when creating collections
49 
50- **Document Operations**
51  - Add documents with optional metadata and custom IDs
52  - Query documents using semantic search
53  - Advanced filtering using metadata and document content
54  - Retrieve documents by IDs or filters
55  - Full text search capabilities
56 
57### Supported Tools
58 
59- `chroma_list_collections` - List all collections with pagination support
60- `chroma_create_collection` - Create a new collection with optional HNSW configuration
61- `chroma_peek_collection` - View a sample of documents in a collection
62- `chroma_get_collection_info` - Get detailed information about a collection
63- `chroma_get_collection_count` - Get the number of documents in a collection
64- `chroma_modify_collection` - Update a collection's name or metadata
65- `chroma_delete_collection` - Delete a collection
66- `chroma_add_documents` - Add documents with optional metadata and custom IDs
67- `chroma_query_documents` - Query documents using semantic search with advanced filtering
68- `chroma_get_documents` - Retrieve documents by IDs or filters with pagination
69- `chroma_update_documents` - Update existing documents' content, metadata, or embeddings
70- `chroma_delete_documents` - Delete specific documents from a collection
71 
72### Embedding Functions
73Chroma MCP supports several embedding functions: `default`, `cohere`, `openai`, `jina`, `voyageai`, and `roboflow`.
74 
75The 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.
76 
77When 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)
78 
79## Usage with Claude Desktop
80 
811. To add an ephemeral client, add the following to your `claude_desktop_config.json` file:
82 
83```json
84"chroma": {
85    "command": "uvx",
86    "args": [
87        "chroma-mcp"
88    ]
89}
90```
91 
922. To add a persistent client, add the following to your `claude_desktop_config.json` file:
93 
94```json
95"chroma": {
96    "command": "uvx",
97    "args": [
98        "chroma-mcp",
99        "--client-type",
100        "persistent",
101        "--data-dir",
102        "/full/path/to/your/data/directory"
103    ]
104}
105```
106 
107This will create a persistent client that will use the data directory specified.
108 
1093. To connect to Chroma Cloud, add the following to your `claude_desktop_config.json` file:
110 
111```json
112"chroma": {
113    "command": "uvx",
114    "args": [
115        "chroma-mcp",
116        "--client-type",
117        "cloud",
118        "--tenant",
119        "your-tenant-id",
120        "--database",
121        "your-database-name",
122        "--api-key",
123        "your-api-key"
124    ]
125}
126```
127 
128This will create a cloud client that automatically connects to api.trychroma.com using SSL.
129 
130**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"]`.
131 
1324. To connect to a [self-hosted Chroma instance on your own cloud provider](https://docs.trychroma.com/
133production/deployment), add the following to your `claude_desktop_config.json` file:
134 
135```json
136"chroma": {
137    "command": "uvx",
138    "args": [
139      "chroma-mcp", 
140      "--client-type", 
141      "http", 
142      "--host", 
143      "your-host", 
144      "--port", 
145      "your-port", 
146      "--custom-auth-credentials",
147      "your-custom-auth-credentials",
148      "--ssl",
149      "true"
150    ]
151}
152```
153 
154This will create an HTTP client that connects to your self-hosted Chroma instance.
155 
156### Demos
157 
158Find 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)
159 
160### Using Environment Variables
161 
162You 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.
163 
164```bash
165# Common variables
166export CHROMA_CLIENT_TYPE="http"  # or "cloud", "persistent", "ephemeral"
167 
168# For persistent client
169export CHROMA_DATA_DIR="/full/path/to/your/data/directory"
170 
171# For cloud client (Chroma Cloud)
172export CHROMA_TENANT="your-tenant-id"
173export CHROMA_DATABASE="your-database-name"
174export CHROMA_API_KEY="your-api-key"
175 
176# For HTTP client (self-hosted)
177export CHROMA_HOST="your-host"
178export CHROMA_PORT="your-port"
179export CHROMA_CUSTOM_AUTH_CREDENTIALS="your-custom-auth-credentials"
180export CHROMA_SSL="true"
181 
182# Optional: Specify path to .env file (defaults to .chroma_env)
183export CHROMA_DOTENV_PATH="/path/to/your/.env" 
184```
185 
186#### Embedding Function Environment Variables
187When using external embedding functions that access an API key, follow the naming convention
188`CHROMA_<>_API_KEY="<key>"`.
189So 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.
190