Chroma

You can run the ChromaDB MCP Server to expose ChromaDB vector database operations as MCP tools. This lets AI assistants and MCP clients interact with your ChromaDB data through a consistent, tool-based interface for collection management, document handling, and vector similarity search.

How to use

Start the MCP server in a transport mode of your choice, then connect your MCP client to the provided endpoint. You will gain access to tools for creating and listing collections, adding and querying documents, and performing semantic searches. Use the HTTP transport to expose the server remotely or on a local port, or use STDIO for direct, local communication with compatible clients.

Typical workflows include: creating a collection with embedding configuration, adding documents with optional metadata and precomputed embeddings, querying with text or embedding vectors, filtering by metadata, updating documents, and deleting documents or entire collections. You can also retrieve statistics and peek at collections to inspect contents.

How to install

Prerequisites you need before installing are Python and a suitable package manager. You will also use a development tool to manage the environment.

# Create virtual environment
python3 -m venv venv

# Activate the virtual environment
source venv/bin/activate

# Install in development mode with all dependencies
pip install hatch
hatch env create
hatch run pip install -e .

# Optional: Install additional embedding providers
pip install -e ".[openai]"          # For OpenAI embeddings
pip install -e ".[cohere]"          # For Cohere embeddings (LangChain compatible)
pip install -e ".[instructor]"      # For Instructor embeddings (LangChain compatible)
pip install -e ".[sentence-transformers]"  # For Sentence Transformers
pip install -e ".[huggingface]"     # For HuggingFace models

Verify the installation and start the server to confirm everything is wired up.

hatch run chroma-mcp-server --help
# or
python -m app.chroma_mcp_server --help

Run the server in a chosen transport mode. The following examples start the server in STDIO, HTTP, or SSE transports.

# STDIO transport (local, default)
python -m app.chroma_mcp_server stdio

# HTTP transport (network accessible) with explicit host/port
python -m app.chroma_mcp_server http 127.0.0.1 8000

# SSE transport (Real-time streaming, legacy; HTTP is recommended)
python -m app.chroma_mcp_server sse 127.0.0.1 8000

Additional content

ChromaDB connection modes let you tailor how the MCP server talks to the database. You can connect via HTTP to a remote or local ChromaDB server, use a local persistent client for offline work, or run an in-memory mode for fast prototyping. You can override configuration via CLI flags or environment variables, with CLI options taking precedence.

To connect ChromaDB with different embedding providers, you can configure embedding provider, model, and API keys in the embedding configuration when you create a collection. This supports providers such as OpenAI, Cohere, Instructor, Sentence Transformers, and HuggingFace.

If you need to connect through a specific host/port for ChromaDB, set the environment variables CHROMA_HOST and CHROMA_PORT or supply them via CLI overrides when starting the MCP server.

Note that the server uses asyncio for non-blocking operation and supports batch operations for efficiency. It also exposes tools to retrieve collection statistics and to peek at documents.

Transport notes

STDIO transport is best for local development and desktop integrations. HTTP transport is best for networked setups with multiple clients. SSE transport provides real-time streaming capabilities but is considered legacy; HTTP is recommended for new projects.

Configuration and environment

The server supports multiple connection modes and lets you configure the active mode using CLI flags or environment variables. CLI flags override values set in environment files. Useful environment variables include CHROMA_HOST, CHROMA_PORT, CHROMA_PERSIST_DIRECTORY, CHROMA_MODE, DEFAULT_EMBEDDING_PROVIDER, DEFAULT_EMBEDDING_MODEL, OPENAI_API_KEY, and COHERE_API_KEY.

Troubleshooting

If you encounter issues, verify that ChromaDB is running at the specified host/port, ensure the correct collection name is used, and confirm that document IDs exist when retrieving or updating documents. Check that all dependencies are installed if you see import or module errors.

Notes on usage with clients

As you connect with LangChain or other MCP-enabled assistants, you can leverage embedding providers to create collections, insert documents with metadata, and perform semantic searches. The server exposes tools that let you manage data and run retrieval-augmented generation workflows.

Available tools

list_collections

List all collections with their metadata.

create_collection

Create a new collection with optional metadata and embedding configuration.

get_collection

Get information about a specific collection.

delete_collection

Delete a collection and all its documents.

add_documents

Add documents to a collection, with optional metadata and embeddings.

query_collection

Perform a semantic search on a collection with text or embedding queries and optional filters.

update_document

Update an existing document's content, metadata, or embedding.

delete_documents

Delete documents from a collection by IDs.

get_document

Retrieve a specific document from a collection.

collection_stats

Get statistics for a collection.

peek_collection

Peek at the first few documents in a collection.