Registry / vector-search / chroma-mcp

chroma-mcp

JSON →
library0.2.6pypypiunverified

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.

pip install chroma-mcp
INSTALL
IMPORT
SIG · CHROMA-MCP
C
chroma-mcp
vector-searchpythonv0.2.6
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

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)
Debug
Known issues
breakingThe `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`.
affects: >=0.2.1
gotchaThe 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.
affects: all
breakingThe 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.
affects: <0.2.2
gotchaSSL/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.
affects: all
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'uvicorn'
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.
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.
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.
Upgrade
Version history
0.2.6latest on PyPI · released Aug 14, 2025
Audit
Dependencies
chromadbrequiredCore vector database dependency, version pinned internally within ranges (e.g., >=0.4.14,<2.0.0).
fastapirequiredFramework used to build the server application.
uvicornrequiredASGI server to run the FastAPI application.
Agent activity
78 hits · last 30 days
node
68
OpenAI (training)
1
Resources
chroma-mcp — pip install chroma-mcp · libregistry