Chroma MCP HTTP Server

Chroma MCP HTTP服务器

最低限度 模型上下文协议（MCP） 暴露正在运行的服务器 色度数据库 例如，对于像Claude Code这样的客户端，通过纯HTTP将MCP工具作为实例。

特性

• HTTP MCP传输(type: "http")与克劳德代码兼容。
• 用途 chromadb.HttpClient 与现有的Chroma服务器进行通信（客户端-服务器模式）。
• 实施MCP生命周期：

- initialize - notifications/initialized - 基本工具调用： tools/query, tools/add_texts （可扩展）。

• 通过Docker/Podman进行容器化，以便在EC2或任何与OCI兼容的运行时环境中进行部署。

服务器充当一个薄的“适配器层”：FastAPI通过HTTP接收MCP JSON-RPC，处理程序将其转换为Chroma客户端调用，并以MCP兼容的JSON返回结果。这种分离使HTTP传输、协议逻辑和矢量DB访问很好地解耦。

建筑

• FastAPI应用程序 作为HTTP服务器和MCP端点(POST / 和 POST /mcp 对于JSON-RPC， GET / 和 GET /mcp 苏格兰和南方能源公司）。
• 配置 通过Pydantic BaseSettings (pydantic-settings)，读取环境变量，如 CHROMA_HOST, CHROMA_PORT, CHROMA_SSL.
• Chroma客户端 创建于 chromadb.HttpClient(host, port, ssl=...).
• JSON-RPC/MCP模型 使用Pydantic实现，包括：

- MCPRequest （支持请求和通知） - MCPQueryParams, MCPAddTextsParams.

配置

环境变量：

• CHROMA_HOST –Chroma服务器的主机名（例如。 chroma-db 在pod或内部DNS中）。
• CHROMA_PORT –Chroma HTTP端口（默认 8000).
• CHROMA_SSL – true 或 false HTTPS与HTTP。
• SERVER_HOST –绑定MCP服务器的地址（默认 0.0.0.0).
• SERVER_PORT –MCP HTTP端口（默认 8013).

所有值都可以通过以下方式覆盖 docker run -e ... / podman run -e ... 或者你的编排者。

在本地运行

# Install dependencies
pip install -e .

# Start the server
uvicorn app.main:app --host 0.0.0.0 --port 8013

# Verify SSE endpoint
curl -i http://127.0.0.1:8013/mcp

你应该看到一个 200 OK 和 content-type: text/event-stream 和一个小 event: endpoint 有效载荷。

Docker/Podman

图像曝光端口 8013 并使用Uvicorn运行FastAPI应用程序。

波德曼的例子：

podman run -d \
  --name mcp-chroma \
  -p 8013:8013 \
  -e CHROMA_HOST=chroma-db \
  -e CHROMA_PORT=8000 \
  -e CHROMA_SSL=false \
  ghcr.io//chroma-mcp-http-server:latest

使用AWS ECR时，请先登录，提取映像，然后如上所述运行它。

Claude代码配置

在您的项目中（例如。 ~/Documents/VektorDB/.mcp.json):

{
  "mcpServers": {
    "chroma": {
      "type": "http",
      "url": "http://>:8013",
      "timeout": 60000
    }
  }
}

然后在Claude Code中，服务器应显示为 connected 在“管理MCP服务器”下。

可以使用Terminal curl进行检查

错误：❯ curl-i http：//：8013/mcp

HTTP/1.1 405方法不允许 日期：2025年12月11日星期四格林尼治标准时间14:19:22 服务器：uvicorn 允许：POST 内容长度：31 内容类型：application/json

｛“detail”：“不允许使用方法”｝%

正确的❯ 卷曲-i \ -X帖子 \ -H“内容类型：应用程序/json” \ http：///mcp \ d “jsonrpc”：“2.0”， “id”：1， “方法”：“初始化”， “params”：｛｝ }'

HTTP/1.1 200可以 日期：2025年12月11日星期四14:20:46格林尼治标准时间 服务器：uvicorn 内容长度：194 内容类型：application/json

｛“jsonrpc”：“2.0”，“id”：1，“结果”：｛“protocolVersion”：“2024-11-05”，“serverInfo”：｛名称：“色度mcp http服务器”，“版本”：“0.1.0”｝，“功能”：｛工具：｛“支持”：true，“listChanged”：true｝｝%

支持的MCP方法

服务器当前处理：

• initialize –返回协议版本、服务器信息和工具功能(tools 支持）
• notifications/initialized –被接受为拒绝通知。
• tools/query –查询Chroma系列 query_texts 和 n_results.
• tools/add_texts –将文档和可选元数据添加到集合中（必要时创建）。

使用更多MCP工具扩展服务器（例如。 tools/list_collections, tools/delete)遵循相同的模式：添加Pydantic参数模型，在 req.method 并调用相应的Chroma客户端API。

发展

• Python≥3.11
• FastAPI+Uvicorn用于HTTP服务器。
• Pydantic v2+ pydantic-settings 用于类型化配置和请求验证。
• chromadb （或 chromadb-client)用于与您的Chroma部署对话。

运行测试（如果添加测试）：

pytest

Linting示例：

ruff check .

______________________________________________________________________