ChromaDB Remote MCP Server

What ChromaDB Remote MCP Server does

ChromaDB Remote MCP Server connects MCP-compatible AI clients to a self-hosted ChromaDB vector database. It translates MCP tool calls into ChromaDB operations for collections, documents, embeddings, metadata, and search. The same deployment can serve Claude Desktop, Claude Mobile, Claude Code, Gemini CLI, Cursor, Cline, Windsurf, VS Code Copilot, and other MCP-compatible clients.

The server also exposes ChromaDB's REST API under /api/v2/*, Swagger UI at /docs, an OpenAPI document at /openapi.json, and an unauthenticated health endpoint at /health. MCP and REST requests use the configured authentication token.

How it works

Clients connect to /mcp using the MCP Streamable HTTP transport. Claude Desktop and Mobile can share a connection configured through a Claude custom connector, while Claude Code uses a separate claude mcp add setup. The remote service authenticates each request, maps MCP operations to ChromaDB, and stores or retrieves vector data from the configured database.

Docker Compose is the primary deployment path. The service can run against a ChromaDB container and persist data through a Docker volume, a local directory, or a custom storage path. Remote access can be provided through a private network such as Tailscale or through the public internet.

Setup and configuration

A one-command installer downloads the Compose configuration, creates or configures storage, pulls the required images, and displays the connection details. Manual deployment is also available with a prebuilt Docker image, a source-based Docker Compose setup, or a local Yarn build.

Copy .env.example to .env before starting the service. Relevant settings include:

• PORT for the external service port, defaulting to 8080.
• CHROMA_DATA_PATH for persistent ChromaDB storage.
• CHROMA_HOST and CHROMA_PORT for the internal ChromaDB address.
• CHROMA_TENANT and CHROMA_DATABASE for the target ChromaDB scope.
• MCP_AUTH_TOKEN for protecting MCP and REST API access.
• CHROMA_AUTH_TOKEN for ChromaDB authentication where applicable.

The MCP endpoint is normally available at http://localhost:8080/mcp, with the health check at http://localhost:8080/health. Generate MCP_AUTH_TOKEN with Node.js or OpenSSL before exposing the service publicly.

Tools and capabilities

Collection tools list, create, get-or-create, modify, delete, inspect, count documents, and count collections. Document tools add, upsert, query, retrieve, update, delete, and preview records; additions and updates can include URIs for multimodal data, while deletion supports IDs and metadata or document filters.

Search includes semantic queries and a hybrid dense-plus-sparse search using reciprocal rank fusion. Query operations can apply URI or ID pre-filters. Operational tools report a heartbeat, server version, maximum batch size, user identity, and indexing status.

Additional tools support zero-copy collection forks, fork metadata lookup, full database reset, and database deletion. Forking and indexing status depend on distributed ChromaDB components such as object storage, metadata services, the WAL, and compactor.

Limitations and notes

Database reset is irreversible. Administrative database deletion requires both of its control flags, so it should be treated as a destructive operation. The hybrid search algorithm operates on a single node, but ChromaDB's open-source local executor does not implement the corresponding search() endpoint. Fork operations and indexing-progress reporting require distributed ChromaDB infrastructure and are not general standalone-node features.

SSE is deprecated for this project; clients should use MCP Streamable HTTP instead. Public deployments should configure an authentication token and protect the remote endpoint appropriately.