Chroma MCP: connection refused (ChromaDB not running or wrong host/port)

TL;DR: Connection refused means ChromaDB is not running where the MCP server is looking. Start ChromaDB, confirm CHROMA_HOST and CHROMA_PORT match, restart the client.

Connection refused

(When the Chroma MCP server dials the ChromaDB instance.)

Fix it

1. Start ChromaDB if it is not running:

chroma run --path ./chroma_db

Or with Docker:

docker run -d -p 8000:8000 chromadb/chroma

2. Verify it answers:

curl http://YOUR_CHROMA_HOST:8000/api/v2/heartbeat

Expected: a JSON heartbeat response.

3. Match the MCP server config to it:

{
  "env": {
    "CHROMA_CLIENT_TYPE": "http",
    "CHROMA_HOST": "YOUR_CHROMA_HOST",
    "CHROMA_PORT": "8000"
  }
}

4. Restart the MCP client.

   Expected: the server connects and collection tools work.

When to use this

• The MCP server fails with connection refused mentioning the Chroma host/port.
• The heartbeat curl also fails (proves ChromaDB is down, not the MCP server).

When NOT to use this

• The heartbeat works but the MCP server still fails. Then the host/port in the client config is wrong.
• Collection not found errors. ChromaDB is up; the collection name is wrong.

Compatibility

• chroma-mcp in http client mode, rkilchmn/chroma-mcp-server.
• ChromaDB local (chroma run) and Docker.

Why it happens

The MCP server is a client of ChromaDB, not a bundle of it. Fresh setups configure the MCP side but never start the database, or start it on a different port. The default port 8000 is a convention, not a guarantee.

Edge cases

• In Docker, the MCP server needs the container or service name as host, not YOUR_HOST.
• chroma run defaults to port 8000. If something else holds 8000, ChromaDB fails to start. Check with lsof -i :8000.
• For embedded/persistent mode, the server uses a data directory instead of host/port. Do not mix the two modes.

The chroma-mcp-server troubleshooting section (rkilchmn/chroma-mcp-server) lists connection refused as a common issue with the fix: ensure ChromaDB is running on the specified host/port. The server supports both local persistent and remote ChromaDB instances, configured via host and port, and a ChromaDB that was never started (or started on a different port) produces connection refused through the MCP tools. Source: https://github.com/rkilchmn/chroma-mcp-server