Chroma MCP Server

0.2.6 · active · verified Fri Apr 17

Chroma MCP (Multi-Modal Controller for Persistance) Server acts as a vector database integration layer for LLM applications. It provides a set of tools that allow LLM agents to interact with ChromaDB, handling complex operations like document creation, updates, and deletions. The current version is 0.2.6, and it sees somewhat frequent updates, often tied to new releases of the underlying `chromadb` library.

Common errors

```
ModuleNotFoundError: No module named 'uvicorn'
```
cause The `uvicorn` package, which is necessary to run the FastAPI server, is not installed in the current environment.

fix Install uvicorn: `pip install uvicorn`
```
RuntimeError: No ChromaDB connection configured. Please set CHROMA_DB_PATH or CHROMA_DB_URI.
```
cause The Chroma MCP Server requires configuration for where its underlying ChromaDB instance should store data or connect. Neither `CHROMA_DB_PATH` nor `CHROMA_DB_URI` environment variables are set.

fix Set either `CHROMA_DB_PATH` to a local directory or `CHROMA_DB_URI` to a remote ChromaDB instance. Example: `export CHROMA_DB_PATH='./chroma_data'` or `os.environ['CHROMA_DB_PATH'] = './chroma_data'`.
```
uvicorn.workers.UvicornWorker: Application 'chroma_mcp.app:app' could not be loaded.
```
cause Uvicorn failed to locate or load the FastAPI application. This can happen if `chroma-mcp` is not installed, the Python path is incorrect, or there's a syntax error within the application itself.

fix Ensure `chroma-mcp` is correctly installed (`pip install chroma-mcp`). Verify that your Python environment is active and that the command `uvicorn chroma_mcp.app:app` is run from a location where `chroma_mcp` is importable.

Warnings

breaking The `chroma-mcp` library frequently updates its internal `chromadb` dependency. Major `chromadb` version bumps (e.g., to 1.0.0 in `chroma-mcp` v0.2.1, then 1.0.3, 1.0.10, 1.0.16 in later versions) can introduce breaking changes or behavioral shifts that might affect how LLM agents interact with the exposed tools if not designed robustly.
Fix: Refer to the `chroma-mcp` release notes and `chromadb` documentation for specific version compatibility and migration guides. Test agent interactions thoroughly after updating `chroma-mcp`.
gotcha The Chroma MCP Server relies heavily on environment variables for configuration (e.g., `CHROMA_DB_PATH`, `CHROMA_DB_URI`, `CHROMA_SERVER_HOST`, `CHROMA_SERVER_PORT`). Incorrect or missing environment variables will prevent the server from starting or connecting to ChromaDB.
Fix: Ensure all necessary environment variables are set correctly before starting the server. Use `.env` files with tools like `python-dotenv` or explicitly set them in your deployment environment.
breaking The behavior of `include` parameters on query and get operations was fixed in v0.2.2 to correctly match the `chromadb` Python client's expectations. This might change the data format or content returned by agent tools if your agents were relying on the previous, possibly incorrect, behavior.
Fix: Update `chroma-mcp` to v0.2.2 or later. Review agent logic that processes query/get results to ensure compatibility with the corrected `include` behavior.
gotcha SSL/TLS configuration (e.g., `CHROMA_SERVER_SSL_KEYFILE`, `CHROMA_SERVER_SSL_CERTFILE`) was enhanced in v0.2.0. Misconfigurations can lead to connection failures or security vulnerabilities. Setting up self-signed certificates for testing can also be complex.
Fix: Carefully follow the documentation for SSL/TLS setup. For testing, consider starting without SSL first to ensure basic connectivity, then introduce SSL gradually. Ensure correct certificate paths and permissions.

Install

pip install chroma-mcp Install stable version

Quickstart

The Chroma MCP Server is a FastAPI application. This quickstart demonstrates how to run it locally using `uvicorn`, configuring the ChromaDB backend via environment variables to use a temporary directory for data storage. The server will start and be accessible at `http://127.0.0.1:8000` (or configured host/port).

import os
import uvicorn
import tempfile
import shutil

# This library is a server application designed to be run, not typically imported
# for client-side functionality. The quickstart demonstrates how to run the server locally.

# Create a temporary directory for ChromaDB to store its data
temp_dir = tempfile.mkdtemp()
print(f"ChromaDB data will be stored in: {temp_dir}")

# Configure the Chroma MCP server via environment variables.
# These are crucial for the server to operate correctly.
os.environ["CHROMA_DB_PATH"] = temp_dir # Use a local persistent ChromaDB path
os.environ["CHROMA_SERVER_HOST"] = os.environ.get('CHROMA_SERVER_HOST', '127.0.0.1')
os.environ["CHROMA_SERVER_PORT"] = os.environ.get('CHROMA_SERVER_PORT', '8000')
os.environ["CHROMA_SERVER_ROOT_PATH"] = os.environ.get('CHROMA_SERVER_ROOT_PATH', '')
os.environ["LOG_LEVEL"] = os.environ.get('LOG_LEVEL', 'info') # Optional: set log level

print(f"Starting Chroma MCP Server on http://{os.environ['CHROMA_SERVER_HOST']}:{os.environ['CHROMA_SERVER_PORT']}")
print("Press Ctrl+C to stop the server.")

try:
    # Run the Chroma MCP FastAPI application using uvicorn.
    # The application instance is found at 'chroma_mcp.app:app'.
    uvicorn.run(
        "chroma_mcp.app:app",
        host=os.environ["CHROMA_SERVER_HOST"],
        port=int(os.environ["CHROMA_SERVER_PORT"]),
        log_level=os.environ["LOG_LEVEL"],
        reload=False # Set to True for development, False for production
    )
except KeyboardInterrupt:
    print("\nServer stopped.")
finally:
    # Clean up the temporary directory used by ChromaDB
    print(f"Cleaning up temporary ChromaDB data directory: {temp_dir}")
    shutil.rmtree(temp_dir)

view raw JSON →