Chroma MCP tool for ADK

Supported in ADKPythonTypeScript

The Chroma MCP Server connects your ADK agent to Chroma, an open-source embedding database. This integration gives your agent the ability to create collections, store documents, and retrieve information using semantic search, full text search, and metadata filtering.

Use cases

Semantic Memory for Agents: Store conversation context, facts, or learned information that agents can retrieve later using natural language queries.
Knowledge Base Retrieval: Build a retrieval-augmented generation (RAG) system by storing documents and retrieving relevant context for responses.
Persistent Context Across Sessions: Maintain long-term memory across conversations, allowing agents to reference past interactions and accumulated knowledge.

Prerequisites

For local storage: A directory path to persist data
For Chroma Cloud: A Chroma Cloud account with tenant ID, database name, and API key

Use with agent

=== "Python"

=== "Local MCP Server"

    ```python
    from google.adk.agents import Agent
    from google.adk.tools.mcp_tool import McpToolset
    from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams
    from mcp import StdioServerParameters

    # For local storage, use:
    DATA_DIR = "/path/to/your/data/directory"

    # For Chroma Cloud, use:
    # CHROMA_TENANT = "your-tenant-id"
    # CHROMA_DATABASE = "your-database-name"
    # CHROMA_API_KEY = "your-api-key"

    root_agent = Agent(
        model="gemini-flash-latest",
        name="chroma_agent",
        instruction="Help users store and retrieve information using semantic search",
        tools=[
            McpToolset(
                connection_params=StdioConnectionParams(
                    server_params=StdioServerParameters(
                        command="uvx",
                        args=[
                            "chroma-mcp",
                            # For local storage, use:
                            "--client-type",
                            "persistent",
                            "--data-dir",
                            DATA_DIR,
                            # For Chroma Cloud, use:
                            # "--client-type",
                            # "cloud",
                            # "--tenant",
                            # CHROMA_TENANT,
                            # "--database",
                            # CHROMA_DATABASE,
                            # "--api-key",
                            # CHROMA_API_KEY,
                        ],
                    ),
                    timeout=30,
                ),
            )
        ],
    )
    ```

=== "TypeScript"

=== "Local MCP Server"

    ```typescript
    import { LlmAgent, MCPToolset } from "@google/adk";

    // For local storage, use:
    const DATA_DIR = "/path/to/your/data/directory";

    // For Chroma Cloud, use:
    // const CHROMA_TENANT = "your-tenant-id";
    // const CHROMA_DATABASE = "your-database-name";
    // const CHROMA_API_KEY = "your-api-key";

    const rootAgent = new LlmAgent({
        model: "gemini-flash-latest",
        name: "chroma_agent",
        instruction: "Help users store and retrieve information using semantic search",
        tools: [
            new MCPToolset({
                type: "StdioConnectionParams",
                serverParams: {
                    command: "uvx",
                    args: [
                        "chroma-mcp",
                        // For local storage, use:
                        "--client-type",
                        "persistent",
                        "--data-dir",
                        DATA_DIR,
                        // For Chroma Cloud, use:
                        // "--client-type",
                        // "cloud",
                        // "--tenant",
                        // CHROMA_TENANT,
                        // "--database",
                        // CHROMA_DATABASE,
                        // "--api-key",
                        // CHROMA_API_KEY,
                    ],
                },
            }),
        ],
    });

    export { rootAgent };
    ```

Available tools

Collection management

Tool	Description
`chroma_list_collections`	List all collections with pagination support
`chroma_create_collection`	Create a new collection with optional HNSW configuration
`chroma_get_collection_info`	Get detailed information about a collection
`chroma_get_collection_count`	Get the number of documents in a collection
`chroma_modify_collection`	Update a collection's name or metadata
`chroma_delete_collection`	Delete a collection
`chroma_peek_collection`	View a sample of documents in a collection

Document operations

Tool	Description
`chroma_add_documents`	Add documents with optional metadata and custom IDs
`chroma_query_documents`	Query documents using semantic search with advanced filtering
`chroma_get_documents`	Retrieve documents by IDs or filters with pagination
`chroma_update_documents`	Update existing documents' content, metadata, or embeddings
`chroma_delete_documents`	Delete specific documents from a collection

Configuration

The Chroma MCP server supports multiple client types to suit different needs:

Client types

Client Type	Description	Key Arguments
`ephemeral`	In-memory storage, cleared on restart. Useful for testing.	None (default)
`persistent`	File-based storage on your local machine	`--data-dir`
`http`	Connect to a self-hosted Chroma server	`--host`, `--port`, `--ssl`, `--custom-auth-credentials`
`cloud`	Connect to Chroma Cloud (api.trychroma.com)	`--tenant`, `--database`, `--api-key`

Environment variables

You can also configure the client using environment variables. Command-line arguments take precedence over environment variables.

Variable	Description
`CHROMA_CLIENT_TYPE`	Client type: `ephemeral`, `persistent`, `http`, or `cloud`
`CHROMA_DATA_DIR`	Path for persistent local storage
`CHROMA_TENANT`	Tenant ID for Chroma Cloud
`CHROMA_DATABASE`	Database name for Chroma Cloud
`CHROMA_API_KEY`	API key for Chroma Cloud
`CHROMA_HOST`	Host for self-hosted HTTP client
`CHROMA_PORT`	Port for self-hosted HTTP client
`CHROMA_SSL`	Enable SSL for HTTP client (`true` or `false`)
`CHROMA_DOTENV_PATH`	Path to `.env` file (defaults to `.chroma_env`)

7.4 KiB Raw Permalink Blame History