Databases·
intermediate
·11 min read·May 30, 2026·Updated Oct 10, 2026
By Rad Tome·Lead AI Systems Architect·How we verify this

ChromaDB Vector Search MCP Server Guide

Connect ChromaDB vector search to AI agents via MCP. Build persistent semantic memory, dynamic embeddings retrieval, and production RAG tool pipelines.

chromadbvector searchragembeddingssemantic memorymodel context protocoldatabases
Interactive Tool
1-Click Export

Generate & Test ChromaDB Vector MCP Server Config

One-click export with environment variables & path locators for Claude Desktop, Cursor, Windsurf, and OpenAI Codex CLI.

Open in Generator

ChromaDB Vector Search MCP Server Guide

Large language model agents excel at deductive reasoning, code generation, and multi-step tool planning. However, because their context windows remain finite and expensive, injecting entire corporate document repositories or software archives directly into prompts is neither scalable nor cost-effective. While traditional SQL and keyword search engines match exact lexical patterns, they struggle with conceptual semantics—such as associating "cloud billing spike mitigation" with "AWS auto-scaling policies".

Connecting a vector database like ChromaDB through a Model Context Protocol (MCP) server equips AI agents with dynamic semantic retrieval. Using high-dimensional embedding spaces, agents running in Claude Desktop, Cursor, or OpenAI Codex CLI can autonomously store code snippets, search documentation by meaning, and pull context-relevant chunks on demand during complex software engineering tasks.

1. Problem Statement and Architecture

Implementing ad-hoc Retrieval-Augmented Generation (RAG) directly inside client prompts introduces several architectural bottlenecks:

  1. ▸Context Window Contamination: Injecting unverified search results into the initial prompt crowds out instructions and increases inference latency. Agents require targeted, tool-based retrieval where they formulate their own semantic queries based on runtime ambiguities.
  2. ▸Dynamic Knowledge Ingestion: Coding assistants frequently create new modules, refactor interfaces, and write test scenarios. Without write-enabled vector tools, the agent cannot index newly generated project knowledge for downstream sessions.
  3. ▸Transport Consistency: Integrating custom vector search traditionally required host-specific plugin frameworks. The Model Context Protocol provides a universal JSON-RPC 2.0 interface that functions identically across all modern developer tools.
code
+-----------------------------------------------------------------------------------+
|                              Client Architecture                                  |
|                                                                                   |
|  +--------------------+        JSON-RPC 2.0 (stdio)        +-------------------+  |
|  |  Claude / Cursor   | <================================> |   chromadb-mcp    |  |
|  +--------------------+                                    +---------+---------+  |
+----------------------------------------------------------------------|------------+
                                                                       | HTTP REST /
                                                                       | Embeddings
                                                                       v
                                                             +-------------------+
                                                             | ChromaDB Instance |
                                                             | (Vector Indices)  |
                                                             +-------------------+

The ChromaDB MCP server operates as an out-of-process daemon that interfaces with a standalone ChromaDB instance running locally in Docker or hosted in cloud infrastructure. It exposes standardized tools for querying collections, inserting vectorized documents, and managing metadata filters.

2. Prerequisites and Environment Matrix

Running the ChromaDB MCP integration requires Node.js 18 or later and a functioning ChromaDB server instance.

ComponentMinimum VersionRecommendedNotes
Node.js18.18.0+20.x LTS or 22.xRuntime for the MCP server
ChromaDB0.4.20+0.5.x+Local Docker container or cloud cluster
Embedding ModelN/ADefault ONNX / OpenAIEmbedding calculation backend
Claude Desktop0.7.0+LatestSupported desktop client
Cursor IDE0.42.0+LatestAgent composer tool runner
OpenAI Codex CLI0.1.0+LatestTerminal-driven workflow harness

Launch a local ChromaDB instance using Docker:

bash
docker run -d --name chromadb -p 8000:8000 chromadb/chroma:latest

Verify that the ChromaDB heartbeat endpoint is reachable:

bash
curl /api/v1/heartbeat

3. Server Implementation and Configuration

Below is a complete, production-ready TypeScript implementation of the ChromaDB MCP server using @modelcontextprotocol/sdk and the official chromadb client.

typescript
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import { ChromaClient } from "chromadb";

const chromaUrl = process.env.CHROMA_URL || "";
const client = new ChromaClient({ path: chromaUrl });

const server = new Server(
  { name: "chromadb-vector-mcp", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "query_collection",
      description: "Search a ChromaDB collection for semantically relevant documents.",
      inputSchema: {
        type: "object",
        properties: {
          collection_name: { type: "string", description: "Target collection name" },
          query_text: { type: "string", description: "Natural language search prompt" },
          n_results: { type: "integer", default: 5, description: "Number of matches to return" }
        },
        required: ["collection_name", "query_text"]
      }
    },
    {
      name: "add_documents",
      description: "Insert text documents into a ChromaDB collection.",
      inputSchema: {
        type: "object",
        properties: {
          collection_name: { type: "string", description: "Target collection name" },
          documents: { type: "array", items: { type: "string" }, description: "Text contents" },
          ids: { type: "array", items: { type: "string" }, description: "Unique document IDs" }
        },
        required: ["collection_name", "documents", "ids"]
      }
    }
  ]
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "query_collection") {
    const { collection_name, query_text, n_results = 5 } = args as any;
    const collection = await client.getCollection({ name: collection_name });
    const results = await collection.query({
      queryTexts: [query_text],
      nResults: n_results
    });
    return {
      content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
    };
  }

  if (name === "add_documents") {
    const { collection_name, documents, ids } = args as any;
    const collection = await client.getOrCreateCollection({ name: collection_name });
    await collection.add({ ids, documents });
    return {
      content: [{ type: "text", text: `Successfully indexed ${documents.length} documents.` }]
    };
  }

  throw new Error(`Tool not found: ${name}`);
});

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch(console.error);

Multi-Host Configuration Snippets

Claude Desktop

In claude_desktop_config.json:

json
{
  "mcpServers": {
    "chromadb": {
      "command": "node",
      "args": ["/absolute/path/to/chromadb-mcp/dist/index.js"],
      "env": {
        "CHROMA_URL": ""
      }
    }
  }
}

Cursor IDE

In .cursor/mcp.json:

json
{
  "mcpServers": {
    "chromadb": {
      "command": "node",
      "args": ["/absolute/path/to/chromadb-mcp/dist/index.js"],
      "env": {
        "CHROMA_URL": ""
      }
    }
  }
}

OpenAI Codex CLI

In ~/.codex/config.toml:

toml
[mcp_servers.chromadb]
command = "node"
args = ["/absolute/path/to/chromadb-mcp/dist/index.js"]
env = { CHROMA_URL = "" }

4. Step-by-Step Tool Discovery and Invocation

When a developer asks: "Search our internal engineering manual for database connection pool tuning guidelines", the host initiates:

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "query_collection",
    "arguments": {
      "collection_name": "engineering_docs",
      "query_text": "database connection pool tuning guidelines",
      "n_results": 2
    }
  }
}

The daemon computes the query embedding, retrieves nearest neighbor records from ChromaDB, and returns structured context blocks:

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[\n  {\n    \"id\": \"doc_842\",\n    \"document\": \"Configure pool size between 10-20 connections per instance. Never exceed database max_connections limit.\",\n    \"distance\": 0.142\n  }\n]"
      }
    ],
    "isError": false
  }
}

5. Common Errors and Production Troubleshooting

1. ECONNREFUSED

  • ▸Symptom: Invocations immediately crash with connection refused errors.
  • ▸Root Cause: The ChromaDB Docker container or background service is not running or is bound to a non-standard port.
  • ▸Solution: Check Docker container status using docker ps and confirm port mapping. Restart the container with docker restart chromadb.

2. Dimension Mismatch (Expected dimension 1536, got 384)

  • ▸Symptom: Document insertion throws embedding shape mismatch errors.
  • ▸Root Cause: Documents were originally indexed using an external model (e.g., OpenAI text-embedding-3-small with 1536 dimensions), but subsequent queries used ChromaDB's default local all-MiniLM-L6-v2 model (384 dimensions).
  • ▸Solution: Always configure a consistent embedding function on both ingestion and query paths when creating collections.

3. High Latency During Initial Query

  • ▸Symptom: The first query tool call takes 5-10 seconds to return.
  • ▸Root Cause: ChromaDB downloads the default ONNX embedding model weights upon first initialization.
  • ▸Solution: Pre-warm the container by executing a dummy query during deployment or container startup before exposing the server to live agent traffic.

6. External Citations and Security Guardrails

Operating vector retrieval pipelines requires foundational data security:

  1. ▸Access Boundaries: Ensure the ChromaDB HTTP port is not exposed to public network interfaces without token authentication.
  2. ▸Tenant Scoping: Use separate collections or metadata partition keys (tenant_id: "acme") to prevent cross-customer data leakage during semantic queries.
  3. ▸Audit Embeddings: Verify that sensitive PII or unencrypted API keys are filtered prior to vectorization.
Technical Changelog

Weekly Protocol Diffs & Verified Drops

New server guides, benchmarks, and security audits. No spam. Unsubscribe anytime.

Zero marketing spam. 1-click unsubscribe anytime.

Ready to Deploy?

Build your full agent toolstack in the Visual Generator

Combine ChromaDB Vector Search with databases, search APIs, and memory graphs in a single configuration file.

Customize in Generator
Developer Verification & Feedback
0 reports

Did this setup guide work with your AI host?

Help test this configuration across Claude, Cursor, and Codex CLI. Be the first to report:

ChromaDB Vector Search MCP Server Guide FAQ

What is the ChromaDB Vector Search MCP Server Guide?

Connect ChromaDB vector search to AI agents via MCP. Build persistent semantic memory, dynamic embeddings retrieval, and production RAG tool pipelines.

How do I configure ChromaDB Vector Search MCP Server Guide in Claude Desktop or Cursor?

You can copy the configuration JSON from our guide or launch the interactive MCP Codex Config Generator at https://mcp-codex.com/generator to export valid configs in 1 click.

Can I use ChromaDB Vector Search MCP Server Guide with the OpenAI Codex CLI?

Yes, OpenAI Codex CLI supports Model Context Protocol. You can add it directly to ~/.codex/config.toml or pass arguments to codex mcp add.

RT

Written by Rad Tome

Lead AI Systems Architect & Maintainer, MCP Codex

@RadTome

Specializing in Model Context Protocol (MCP) integrations, autonomous AI agent orchestration, and distributed developer toolchains. Researches and benchmarks production MCP client-server architectures across OpenAI Codex, Claude, and Cursor.

Editorial Integrity: Package names are checked against the npm registry and repositories against the GitHub API. Where a package could not be verified, the guide says so instead of giving you a command to run.

Related Guides

Databases

Neo4j Knowledge Graph MCP Server Guide

Connect Neo4j knowledge graphs to AI agents via MCP. Run Cypher queries, traverse entity relationships, and build structured GraphRAG pipelines.

Databases

Connecting Turso & LibSQL Edge Databases to AI Agents using MCP

Connect globally distributed LibSQL/Turso databases to AI agents. Expose safe read-only SQL execution tools for remote data queries.

Databases

MySQL MCP Server Guide: Setup and Queries

Connect MySQL databases to Model Context Protocol agents: Step-by-step configuration, read-only permissions, schema discovery, and query execution.