How to add Chroma MCP Server to Windsurf

Official Chroma server: create collections and run vector, full-text, and metadata search. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 15, 2026 · 600★ · stdio · apikey · official

Windsurf config for Chroma MCP Server

uvx chroma-mcp --client-type persistent --data-dir /absolute/path/to/data

{
  "mcpServers": {
    "chroma-mcp-server": {
      "command": "uvx",
      "args": [
        "chroma-mcp",
        "--client-type",
        "persistent",
        "--data-dir",
        "/absolute/path/to/data"
      ]
    }
  }
}

Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the Chroma MCP Server config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5Chroma MCP Server's tools become available to Cascade.

Before you start

Python with the `uv`/`uvx` package manager (Docker image also provided)
A storage target depending on client type: nothing for `ephemeral`, a directory for `persistent`, a server URL for `http`, or a Chroma Cloud account for `cloud`
For Chroma Cloud: a tenant ID, database name, and API key from your Chroma Cloud account (trychroma.com)
For external embeddings: the provider's API key set as `CHROMA_<PROVIDER>_API_KEY` (e.g. `CHROMA_OPENAI_API_KEY`, `CHROMA_COHERE_API_KEY`)

What Chroma MCP Server can do in Windsurf

chroma_list_collections

List all collections in the database

chroma_create_collection

Create a new collection (optionally with an embedding function/config)

chroma_peek_collection

Preview a few sample records from a collection

chroma_get_collection_info

Get metadata and configuration for a collection

chroma_get_collection_count

Return the number of documents in a collection

chroma_modify_collection

Rename or update a collection's metadata

chroma_delete_collection

Delete a collection

chroma_add_documents

Add documents (with ids/metadata) to a collection, embedding them on insert

Security

Cloud mode requires a Chroma API key that grants tenant/database access, so keep it out of shared config. Persistent mode writes to a local data directory, so point --data-dir at a path you control and trust.

Chroma MCP Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Chroma MCP Server config there under the "mcpServers" key and restart the client.

Is Chroma MCP Server safe to use with Windsurf?

What client types are supported?

Four: `ephemeral` (in-memory, for testing), `persistent` (local directory), `http` (self-hosted Chroma server), and `cloud` (Chroma Cloud). Set it with `--client-type` or `CHROMA_CLIENT_TYPE`.

Do I need an embedding API key?

Not for the default embedding function. You only need a provider key (set as `CHROMA_<PROVIDER>_API_KEY`) if you choose OpenAI, Cohere, Jina, VoyageAI, or Roboflow embeddings.

How do I connect to Chroma Cloud?

Use `--client-type cloud` with your tenant ID, database name, and API key (via `--tenant`/`--database`/`--api-key` or the corresponding `CHROMA_*` env vars) from your Chroma Cloud account.

View repo Full Chroma MCP Server page