ChromaDB Remote MCP Server

ChromaDB 远程 MCP 服务

一个 Streamable HTTP MCP（模型上下文协议）服务，为 Claude 等 AI 助手提供对 ChromaDB 的远程访问。支持从移动设备和远程位置进行语义搜索和向量数据库操作。

注意：本项目使用 MCP Streamable HTTP（2025-03-26 规范）。SSE 传输已弃用。

한국어 문서

---

跨平台 AI 记忆服务

兼容所有主流 AI 平台：

• Claude（桌面端、移动端、Code）
• Gemini（CLI、Code Assist）
• Cursor、Cline、Windsurf、VS Code Copilot
• 还可通过 Remote MCP 配合任何其他兼容 MCP 的客户端使用

功能

远程 MCP 服务，使所有 Claude 客户端（桌面端、Code、移动端）都能访问同一个可自托管的 ChromaDB 实例。

• 跨设备共享记忆 - 所有 Claude 客户端使用同一个 ChromaDB 实例
• 可自托管且私密 - 您的数据保留在自己的基础设施中
• 远程访问 - 通过 Tailscale 或公共互联网从任何位置连接
• 完整的 ChromaDB 支持 - 通过 MCP 工具执行所有 CRUD 操作
• REST API 代理 - 直接通过 Python/JavaScript 访问 ChromaDB
• 统一身份验证 - 单个令牌同时保护 MCP 和 REST API 端点
• 轻松部署 - 使用 Docker 一键安装

---

架构

概览

┌──────────────────────────────┐      ┌──────────────┐
│   Claude Desktop + Mobile    │      │  Claude Code │
│  (Custom Connector - synced) │      │  (CLI setup) │
└──────────────┬───────────────┘      └──────┬───────┘
               │                             │
               │     MCP Remote Connector    │
               └─────────────┬───────────────┘
                             │ HTTPS
                   ┌─────────▼──────────┐
                   │   Remote MCP       │
                   │   Server (Node.js) │
                   │                    │
                   │ • Auth Gateway     │
                   │ • MCP Protocol     │
                   │ • REST API Proxy   │
                   └─────────┬──────────┘
                             │
                   ┌─────────▼──────────┐
                   │     ChromaDB       │
                   │ (Vector Database)  │
                   │                    │
                   │ • Embeddings       │
                   │ • Collections      │
                   │ • Semantic Search  │
                   └────────────────────┘

客户端连接方式：

• Claude Desktop + Mobile：在 Claude Desktop 中使用自定义连接器设置一次，即可自动同步到移动应用。两者会自动共享同一连接。
• Claude Code：需要使用 claude mcp add CLI 命令单独设置。

所有客户端都通过此远程 MCP 服务访问同一个可自托管的 ChromaDB。向量嵌入和语义搜索结果会在所有平台间持久保留。

API 端点

路径	用途	客户端	身份验证
/mcp	MCP 协议	Claude Desktop/Code/Mobile	✅
/api/v2/*	ChromaDB REST API	Python	✅
/docs	Swagger UI	浏览器（API 文档）	✅
/openapi.json	OpenAPI 规范	API 工具	✅
/health	健康检查	监控	❌

工作原理

1. Claude Desktop/Mobile：通过自定义连接器添加 MCP 服务（设备间自动同步）
2. Claude Code：使用 claude mcp add CLI 命令添加 MCP 服务
3. 远程 MCP 服务验证请求，并将 MCP 协议转换为 ChromaDB 操作
4. ChromaDB存储并检索用于语义搜索的向量嵌入
5. Python也可以通过代理 REST API 直接访问 ChromaDB

优点：

• 所有客户端使用同一个向量数据库
• 桌面端和移动端自动共享连接
• 可自托管且私密
• 应用重启后记忆仍会保留
• 嵌入数据的单一事实来源

---

快速开始

单命令安装

curl -fsSL https://raw.githubusercontent.com/meloncafe/chromadb-remote-mcp/release/scripts/install.sh | bash

此命令将：

1. 下载 docker-compose.yml 和 .env.example
2. 自动检测 Docker Compose 命令（docker-compose 或 docker compose）
3. 自动生成安全的身份验证令牌（可选）
4. 配置 ChromaDB 数据存储位置（Docker 卷、本地目录或自定义路径）
5. 拉取 Docker 镜像
6. 显示身份验证令牌和连接 URL

手动安装

选项 1：Docker（推荐 - 预构建镜像）

# Download configuration files
mkdir chromadb-remote-mcp && cd chromadb-remote-mcp
curl -O https://raw.githubusercontent.com/meloncafe/chromadb-remote-mcp/release/docker-compose.yml
curl -O https://raw.githubusercontent.com/meloncafe/chromadb-remote-mcp/release/.env.example

# Configure environment
cp .env.example .env
# Edit .env and set:
#   - MCP_AUTH_TOKEN (see token generation below)
#   - PORT (default: 8080)
#   - CHROMA_DATA_PATH (default: chroma-data)

# Start services
docker compose up -d
# or: docker-compose up -d (for older versions)

# Check health
curl http://localhost:8080/health

# View logs
docker compose logs -f

选项 2：从源代码构建

# Clone repository
git clone https://github.com/meloncafe/chromadb-remote-mcp.git
cd chromadb-remote-mcp

# Configure environment
cp .env.example .env
# Edit .env with your configuration

# Start with docker-compose (builds image from source)
docker compose -f docker-compose.dev.yml up -d
# or: docker-compose -f docker-compose.dev.yml up -d (for older versions)

选项 3：本地开发

# Clone and install
git clone https://github.com/meloncafe/chromadb-remote-mcp.git
cd chromadb-remote-mcp
yarn install

# Configure environment
cp .env.example .env
# Edit .env file

# Build and run
yarn build
yarn start

生成安全令牌

在生产环境中使用时，请为 .env 中的 MCP_AUTH_TOKEN 生成安全令牌：

# Method 1: Node.js (Recommended)
node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

# Method 2: OpenSSL
openssl rand -base64 32 | tr '+/' '-_' | tr -d '='

复制生成的令牌并粘贴到 .env 文件中：

MCP_AUTH_TOKEN=your-generated-token-here

服务端点

• MCP：http://localhost:8080/mcp（通过 Caddy 代理）
• 健康检查：http://localhost:8080/health
• ChromaDB API：http://localhost:8080/api/v2/*
• Swagger UI：http://localhost:8080/docs

---

配置

环境变量（.env 文件）

所有配置都通过 .env 文件完成。将 .env.example 复制为 .env 并进行自定义：

cp .env.example .env

变量	说明	默认值	必填
PORT	外部端口（Caddy 反向代理）	8080	否
CHROMA_DATA_PATH	ChromaDB 数据存储路径（卷名称、./data 或绝对路径）	chroma-data	否
CHROMA_HOST	ChromaDB 主机（内部）	chromadb	否
CHROMA_PORT	ChromaDB 端口（内部）	8000	否
CHROMA_TENANT	ChromaDB 租户	default_tenant	否
CHROMA_DATABASE	ChromaDB 数据库	default_database	否
MCP_AUTH_TOKEN	MCP 和 REST API 的身份验证令牌	-	是（用于公开访问）
CHROMA_AUTH_TOKEN	ChromaDB 身份验证令牌（如果 ChromaDB 要求身份验证）	-	否
RATE_LIMIT_MAX	每个 IP 每 15 分钟的最大请求数	100	否
ALLOWED_ORIGINS	允许的来源列表，以逗号分隔（DNS 重绑定保护）	-	否
CHROMA_SERVER_VERSION	由操作者声明的 Chroma 服务版本——供 chroma_get_server_version 和 /health/detail 使用，作为可信版本来源。警告：使用 chromadb/chroma:latest 镜像时，该值不会随镜像更新，因此可能不一致——请固定版本标签，并将此值设置为相同版本。	未设置时为 unknown；docker-compose.yml 默认值为 1.5.9	否
MCP_SERVER_VERSION	MCP 封装器版本——在发布镜像中自动设置（发布标签 → VERSION 构建参数）；无需手动设置	未设置时为 dev	否

身份验证

**重要：**对于公共互联网访问（Tailscale Funnel、Cloudflare Tunnel 等），必须在 .env 文件中设置 MCP_AUTH_TOKEN。

生成安全令牌：

# Method 1: Node.js (Recommended - from .env.example)
node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

# Method 2: OpenSSL
openssl rand -base64 32 | tr '+/' '-_' | tr -d '='

编辑 .env 文件：

MCP_AUTH_TOKEN=your-generated-token-here

然后重启服务：

docker compose restart
# or: docker-compose restart

支持的身份验证方式（v2.0.0）：

1. Authorization: Bearer TOKEN — 这是发送 MCP_AUTH_TOKEN 的唯一支持方式。

   • 推荐用于服务间调用方（API 客户端、脚本、MCP 中继）。
   • 符合 MCP 规范。
   • 示例：curl -H "Authorization: Bearer YOUR_TOKEN" https://your-server.com/mcp

2. OAuth 2.1 / OpenID Connect — 推荐用于人类用户。

   • 设置 OIDC_ISSUERS（以逗号分隔的颁发者 URL）或 OIDC_PRESET=google,github,microsoft。
   • 将 OIDC_AUDIENCE 设置为资源标识符（通常是 MCP 服务的公共 URL）。
   • 服务会在 /.well-known/oauth-protected-resource 发布 RFC 9728 受保护资源元数据。
   • 根据 RFC 6750，401 响应会包含 WWW-Authenticate: Bearer error="...", resource_metadata="..."。

**在 v2.0.0 中移除：**不再接受 X-Chroma-Token 标头以及 ?apiKey= / ?token= / ?api_key= 查询参数身份验证。之前使用这些方式的客户端必须迁移到 Authorization: Bearer。ALLOW_QUERY_AUTH 环境变量会被忽略。

Origin 标头验证（DNS 重绑定防护）

服务会验证浏览器请求的 Origin 标头，以防止 DNS 重绑定攻击。此安全功能默认启用，可保护你的本地 MCP 服务免受恶意网站攻击。

默认允许的来源（始终允许）：

• Localhost 变体：localhost、127.0.0.1、[::1]
• Claude.ai 域名：https://claude.ai、https://api.anthropic.com

配置其他允许的来源：

如果需要允许其他 Web 应用或自定义域名，请将其添加到 .env 文件中的 ALLOWED_ORIGINS：

# Add additional custom domains (Claude.ai is already allowed by default)
ALLOWED_ORIGINS=https://myapp.com,https://yourdomain.com

何时配置 ALLOWED_ORIGINS：

• ✅ 使用 Claude Desktop Custom Connector → 无需配置（默认允许）
• ✅ 从自定义 Web 应用访问 → 添加应用的域名
• ✅ 远程使用 Swagger UI → 添加服务的域名
• ❌ 使用 Claude Code CLI → 无需配置（没有 Origin 标头）
• ❌ 使用 Python/JavaScript 客户端 → 无需配置（没有 Origin 标头）
• ❌ 仅用于本地开发 → 无需配置（默认允许 localhost）

配置示例：

# For custom web application
ALLOWED_ORIGINS=https://myapp.com,https://app.mycompany.com

# Multiple custom domains (comma-separated, spaces are trimmed)
ALLOWED_ORIGINS=https://myapp.com, https://api.example.com, https://dashboard.mycompany.com

# Leave empty if you only need Claude.ai and localhost
ALLOWED_ORIGINS=

**注意：**即使 ALLOWED_ORIGINS 为空，Claude.ai 域名（https://claude.ai、https://api.anthropic.com）和 localhost 也始终允许。服务间请求（不带 Origin 标头）始终允许。

数据存储配置

ChromaDB 数据可以通过三种方式存储：

1. Docker 卷（默认）：CHROMA_DATA_PATH=chroma-data

   • 由 Docker 管理
   • 容器重启后仍会保留
   • 使用 docker volume ls 和 docker volume inspect chroma-data 查找位置

2. 本地目录：CHROMA_DATA_PATH=./data

   • 便于备份和访问
   • 存储在安装目录中

3. 自定义路径：CHROMA_DATA_PATH=/path/to/data

   • 必须是绝对路径
   • 适用于挂载外部存储

更改 CHROMA_DATA_PATH 后，重启服务：

docker compose restart

---

连接 Claude

Claude 桌面端 + 移动端

方法 1：自定义连接器（推荐，适用于 Pro/Team/Enterprise）

1. 打开 Claude Desktop → Settings → Integrations → Custom Connector
2. 点击“Add Custom Server”
3. 输入：
   • 名称：ChromaDB
   • URL：https://your-server.com/mcp（在连接器的标头配置中设置 Authorization: Bearer YOUR_TOKEN）

注意：自定义连接器会自动同步到移动应用。远程访问必须进行身份验证。

方法 2：mcp-remote 包装器（适用于免费版/Pro 用户）

如果无法使用自定义连接器，可使用 mcp-remote 包作为替代方案：

配置文件位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

添加到配置文件：

{
  "mcpServers": {
    "chromadb": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-server.com/mcp", "--header", "Authorization: Bearer YOUR_TOKEN"]
    }
  }
}

编辑文件后重启 Claude Desktop。

重要：无法在 claude_desktop_config.json 中直接使用 streamableHttp 传输配置远程 MCP 服务。必须使用自定义连接器或 mcp-remote 包装器。

Claude Code

CLI 命令：

# Without authentication
claude mcp add --transport http chromadb https://your-server.com/mcp

# With authentication (Query Parameter - Recommended)
claude mcp add --transport http chromadb https://your-server.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

# With authentication (Header)
claude mcp add --transport http chromadb https://your-server.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

# Verify
claude mcp list

---

可用工具（v2.2.0）

该 MCP 服务为 Claude 提供以下工具。v2.2.0 将覆盖范围扩展至 30 个工具，涵盖集合、文档、搜索、分叉、客户端信息、管理和破坏性操作等类别。

集合管理

• chroma_list_collections - 列出所有集合（支持 limit / offset）
• chroma_create_collection - 创建新集合（configuration / schema 可选）
• chroma_get_or_create_collection - 幂等地创建或获取（v2.2.0）
• chroma_modify_collection - 重命名／更改元数据或配置（v2.2.0）
• chroma_delete_collection - 删除集合
• chroma_get_collection_info - 获取集合元数据
• chroma_get_collection_count - 获取文档数量（read_level 可选）
• chroma_count_collections - 集合总数（v2.2.0）
• chroma_peek_collection - 预览集合内容

文档操作

• chroma_add_documents - 添加文档（支持用于多模态数据的 uris）
• chroma_upsert_documents - 幂等地插入或更新（v2.2.0）
• chroma_query_documents - 语义搜索（支持 query_uris / ids 预筛选）
• chroma_get_documents - 检索文档（read_level 可选）
• chroma_update_documents - 更新现有文档（支持 embeddings / uris）
• chroma_delete_documents - 按 ids 和／或 where / where_document 筛选条件删除

服务信息（v2.2.0）

• chroma_heartbeat - 服务心跳（纳秒时间戳）
• chroma_get_server_version - 服务版本字符串
• chroma_get_max_batch_size - 最大批次大小（用于客户端拆分）
• chroma_get_user_identity - 当前租户和数据库

分布式／仅限云端 — 选择启用（CHROMA_DISTRIBUTED_TOOLS_ENABLED=true）

这 4 个工具需要 ChromaDB 的分布式执行器（执行器是 chromadb-server 内部的前端层，并非算法层面的分布式要求）。单节点开源服务（chromadb/chroma:latest Docker 镜像）自带本地执行器，其中这些方法在 rust/frontend/src/executor/local.rs 和 rust/types/src/api_types.rs 中被硬编码为 unimplemented。要使用这些工具，你需要 Chroma Cloud（CloudClient）或可自托管的分布式 Chroma 部署（Kubernetes 多组件架构：前端 + 查询执行器 + WAL + 压实器 + 对象存储）。

默认隐藏，避免单节点部署将 LLM 上下文浪费在始终返回 "not implemented for local executor"／"unsupported for local chroma" 的工具上。

• chroma_search - 混合密集 + 稀疏搜索（RRF）。该算法本身可在单节点上运行；只是 chromadb 开源版尚未在本地执行器中实现 search() 端点。
• chroma_fork_collection - 零拷贝分叉（对象存储上的分段级操作，架构上需要分布式压实器／存储栈）。
• chroma_get_fork_count - 分叉元数据查询（依赖分布式元数据存储）。
• chroma_get_indexing_status - WAL 偏移量 + 压实器索引进度（需要分布式 WAL／压实器服务）。

管理 — 选择启用（CHROMA_ADMIN_TOOLS_ENABLED=true）

• chroma_admin_create_database / chroma_admin_get_database / chroma_admin_list_databases
• chroma_admin_create_tenant / chroma_admin_get_tenant

破坏性操作 — 选择启用（CHROMA_ALLOW_DESTRUCTIVE_OPS=true）

调用会输出一条 [DESTRUCTIVE] 审计记录。

• chroma_reset_database - 重置整个数据库（不可撤销）
• chroma_admin_delete_database - 删除数据库（需要同时启用两个标志）

---

在 Python 中使用 ChromaDB

MCP 服务代理所有 ChromaDB REST API 端点，允许从 Python 客户端直接访问。

Python 示例

import chromadb

# HTTPS (Tailscale Funnel, public deployment)
client = chromadb.HttpClient(
    host="your-server.com",
    port=443,
    ssl=True,
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    }
)

# Local development (HTTP)
client = chromadb.HttpClient(
    host="localhost",
    port=8080,
    ssl=False,
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    }
)

# Usage
collection = client.create_collection("my_collection")
collection.add(
    documents=["Document 1", "Document 2"],
    ids=["id1", "id2"]
)
results = collection.query(query_texts=["query"], n_results=2)

其他身份验证方式：

from chromadb.config import Settings

client = chromadb.HttpClient(
    host="your-server.com",
    port=443,
    ssl=True,
    settings=Settings(
        chroma_client_auth_provider="chromadb.auth.token_authn.TokenAuthClientProvider",
        chroma_client_auth_credentials="YOUR_TOKEN"
    )
)

API 文档

访问 https://your-server.com/docs，查看所有 ChromaDB REST API 端点的 Swagger UI 文档。

---

部署

使用 deploy.sh 部署

deploy.sh 在一个脚本中封装了本仓库 docker-compose.yml 的 Docker Compose 生命周期。该脚本与主机无关：所有主机特定设置都放在 .env（参见 .env.example）和可选的额外 compose 文件中，不会写入脚本。

命令	作用
./deploy.sh install	首次设置。若 .env 不存在，则从 .env.example 创建，并暂停以便你编辑；否则拉取镜像并启动服务
./deploy.sh update	拉取镜像，重新创建容器（up -d --force-recreate），清理悬空镜像，同步 .env 中的 CHROMA_SERVER_VERSION，然后复用同一次判定结果打印版本信息
./deploy.sh start	启动服务（up -d）
./deploy.sh stop	停止并移除容器（down）；数据会保留
./deploy.sh restart	重启容器。不会重新读取 .env——修改该文件后，请使用 update 或 start
./deploy.sh status	执行 docker compose ps，并显示 chromadb / chroma-mcp-server / caddy-proxy 容器的状态
./deploy.sh logs [service]	持续跟踪日志（--tail=100），例如 ./deploy.sh logs mcp-server
./deploy.sh version	显示 MCP 镜像和运行中容器的版本，以及固定的 Chroma 镜像；根据运行中镜像的摘要解析 Chroma 服务版本，并将其记录到 .env
./deploy.sh backup	将 Chroma 数据归档到 backups/chromadb_data_<timestamp>.tar.gz（见下文）
./deploy.sh self-update [tag]	使用 GitHub 发行版中的文件替换 deploy.sh、docker-compose.yml、docker-compose.traefik.example.yml 和 .env.example（默认：最新版本）。绝不修改 .env、本地 Compose 覆盖文件和数据（见下文）

./deploy.sh help 会打印用法说明。

设置 — 从主机的 .env 读取（同名的进程环境变量优先）：

键	含义	默认值
COMPOSE_FILE	按顺序合并的 Compose 文件，以 : 分隔	docker-compose.yml
COMPOSE_PATH_SEPARATOR	COMPOSE_FILE 列表的分隔符	:
COMPOSE_PROJECT_NAME	Compose 项目名称；它会作为网络和命名卷（<project>_chroma-data）的前缀。首次启动后更改此名称，会为命名卷堆栈创建一个新的空卷；绑定路径则会保留数据	部署目录名称
CHROMA_DATA_PATH	Chroma 数据：Compose 命名卷 chroma-data，或绝对路径 / ./相对路径 绑定路径	chroma-data（命名卷）
PORT	caddy 发布到主机的端口	8080
MCP_IMAGE_TAG	devsaurus/chromadb-remote-mcp 镜像的标签	latest
DEPLOY_LANG	deploy.sh 的消息语言：en 或 ko	根据区域设置

从进程环境中读取 DRY_RUN=1、DEPLOY_DIR=<dir>（测试用目标目录）和 CHROMA_IMAGE=<ref>（不存在 chromadb 容器时用于备份 tar 的镜像）。

每台主机仅运行一个堆栈 — docker-compose.yml 固定了 container_name（chromadb、chroma-mcp-server、caddy-proxy），因此，仅更改 COMPOSE_PROJECT_NAME 无法让同一台主机运行第二个堆栈：容器名称会冲突。

Compose 文件选择 — COMPOSE_FILE 是按顺序合并的列表（后面的文件会覆盖前面的文件），与 docker compose 的行为完全相同。相对路径条目相对于部署目录解析，绝对路径条目则保持不变。deploy.sh 每次调用都会传入 --project-directory，因此 .env 和相对路径始终指向部署目录。

DRY_RUN=1 — 打印每条以 [DRY-RUN] 为前缀的 docker 命令，不调用 docker，也不修改任何文件；即使未安装 docker 也能运行。install 会打印执行计划，但不会复制 .env 或创建 backups/；version / update 会跳过摘要判定、.env 写入和 mcp-server 重建。若 .env 缺失，则降级为警告：根据已提交的 .env.example / Compose 默认值打印计划，不会创建任何文件。不使用 DRY_RUN 时，缺少 .env 仍然会报错。

DRY_RUN=1 ./deploy.sh update

输出语言 — 帮助和日志消息使用英语或韩语。语言由 DEPLOY_LANG 决定（先检查环境变量，再检查 .env）；如果未设置，则取 LC_ALL、LC_MESSAGES、LANG 中第一个非空值：以 ko 开头的值选择韩语，其他值选择英语。

CHROMA_SERVER_VERSION 的处理方式 — Chroma 服务报告的是硬编码的 1.0.0，因此 update / version 会将 chromadb 容器镜像的 RepoDigest 与 compose 文件中固定的摘要进行比较，然后再与 Docker Hub 上固定标签的摘要进行比较，并将结果记录到 .env 中。值发生变化时，仅重新创建 mcp-server（使用 up -d）。如果无法确定版本（包括仅匹配 Docker Hub 的 latest 标签），则在发出警告的同时保留现有 .env 值；只有在尚无值时才写入 unknown。

备份 — ./deploy.sh backup 通过临时容器和只读挂载读取数据，因此 root 所有的绑定目录和命名卷都能正常使用。数据位置会自动检测：首先检查现有 chromadb 容器的 /data 挂载，否则使用 .env 中的 CHROMA_DATA_PATH（绝对路径、./ 或 ../ 路径表示绑定挂载；普通名称——默认值为 chroma-data——表示 compose 命名卷 <project>_<name>）。归档先写入 .tar.gz.partial，成功后再重命名（失败时删除）。为确保快照一致，备份期间会停止 chromadb；仅当备份前 chromadb 正在运行时，备份结束后才会重新启动。如果备份收到 SIGINT 或 SIGTERM（例如 Ctrl+C），则会删除 .tar.gz.partial 文件；如果备份前 chromadb 正在运行，则重新启动它；最后以退出码 130（SIGINT）或 143（SIGTERM）退出。

自我更新 — ./deploy.sh self-update [tag] 会从 GitHub 发布标签（默认：最新发布版本；也可使用 DEPLOY_TAG 或 --tag）下载由仓库管理的文件到暂存目录，并对其进行验证（文件非空、对脚本运行 bash -n、compose 文件包含 services:，以及在发布版本提供 SHA256SUMS 时验证该文件）；随后将当前文件备份到 backups/self-update_<timestamp>_<version>/，并以原子方式逐个替换文件（临时文件 + mv）；若发生任何故障或中断，则恢复备份。它会显示当前版本和目标版本（已安装的标签记录在 .deploy-release 中）。不会触碰 .env、不属于发布版本的本地 compose 覆盖文件以及数据目录。此命令拒绝在 git checkout 目录中运行（请改用 git pull），并支持 DRY_RUN=1。DEPLOY_REPO（默认值为 meloncafe/chromadb-remote-mcp）和 SELF_UPDATE_FILES 可分别覆盖源代码仓库和文件列表。update（镜像）与 self-update（脚本/compose）有意分开：在 update 期间替换 compose 文件会改变拉取/重建所依据的配置，因此 update 只会显示提示，而 self-update 会在结束时提示你运行 update。

在 Traefik 反向代理后运行 — docker-compose.traefik.example.yml 是一个可选的示例覆盖文件，其中包含占位变量。复制它，将副本保留在服务器上，并通过 .env 中的 compose 文件列表选择它：

cp docker-compose.traefik.example.yml docker-compose.traefik.yml

# .env
COMPOSE_FILE=docker-compose.yml:docker-compose.traefik.yml
TRAEFIK_HOST=mcp.example.com
TRAEFIK_CERT_RESOLVER=your-resolver

./deploy.sh update

TRAEFIK_HOST 和 TRAEFIK_CERT_RESOLVER 为必填项。可选项：TRAEFIK_NETWORK（Traefik 所连接的外部网络，该网络必须已存在；默认值为 traefik）、TRAEFIK_ENTRYPOINT（默认值为 websecure）、TRAEFIK_MIDDLEWARES（逗号分隔；参见下方说明）和 TRAEFIK_ROUTER_NAME（默认值为 chromadb-mcp）。Traefik 路由器和服务名称是全局的，因此请选择一个该 Traefik 上其他容器都未使用的 TRAEFIK_ROUTER_NAME。此示例使用 !reset 移除基础文件中的主机端口映射，这需要 Docker Compose 2.24 或更高版本。 docker-compose.traefik.example.yml 中的 middlewares 标签默认处于注释状态，因此不会附加任何中间件。取消该标签的注释后，TRAEFIK_MIDDLEWARES 就成为必填项：不仅未设置该变量会导致中止，空值（TRAEFIK_MIDDLEWARES=）也会导致中止，并提示 required variable TRAEFIK_MIDDLEWARES is missing a value。若要在不使用中间件的情况下运行，请保持该标签处于注释状态。

选项 1：Tailscale VPN（推荐）

在 Tailscale 网络内安全访问：

# Start services
docker compose up -d

# Enable Tailscale Serve (HTTPS with automatic certificates)
tailscale serve https / http://127.0.0.1:8080

# Check status
tailscale serve status

现在，Tailnet 中的所有设备都可以通过 https://your-machine.tailXXXXX.ts.net 访问你的服务器。

优点：

• 自动获取 HTTPS 证书
• 不暴露于公共互联网
• 加密的 VPN 隧道
• 身份验证可选（VPN 提供安全保障）

选项 2：Tailscale Funnel（公共互联网）

用于 Claude Desktop UI 自定义连接器或公开共享：

# Enable Funnel (allows public internet access)
tailscale funnel 8080 on
tailscale serve https / http://127.0.0.1:8080

# Verify Funnel is active
tailscale serve status  # Should show "Funnel on"

警告：这会将你的服务器暴露到公共互联网。必须启用身份验证！ 请在环境中设置 MCP_AUTH_TOKEN。

禁用 Funnel：

tailscale funnel 8080 off

选项 3：Cloudflare Tunnel

# Install cloudflared
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
chmod +x cloudflared

# Authenticate
./cloudflared tunnel login

# Create tunnel
./cloudflared tunnel create chroma-mcp

# Run tunnel
./cloudflared tunnel --url http://localhost:3000

选项 4：Nginx 反向代理

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

---

安全

代码质量与安全分析

本项目遵循严格的安全实践，并已解决静态分析识别出的所有安全问题：

• ✅ 无未解决问题：已解决所有 OWASP 和 CWE 安全发现
• 🔒 静态分析：通过 DeepSource 持续监控
• 🛡️ 安全标准：符合 OWASP Top 10 和 Node.js 安全最佳实践
• 📊 自动扫描：Dependabot、CodeQL 和容器漏洞扫描

有关详细的安全信息，请参阅安全策略。

安全建议

1. 为公共访问启用身份验证

   • 使用 Tailscale Funnel 或公共互联网时，请设置 MCP_AUTH_TOKEN
   • 生成强令牌：openssl rand -base64 32 | tr '+/' '-_' | tr -d '='
   • 定期轮换令牌

2. 使用 HTTPS

   • Tailscale 会自动提供 HTTPS 证书
   • 在其他部署方式中，使用 Nginx/Caddy 反向代理和 Let's Encrypt

3. 优先使用 VPN，而非公共互联网

   • Tailscale Serve（仅限 VPN）比 Funnel（公共访问）更安全
   • 在 VPN 内可选用身份验证，但公共访问必须启用身份验证

4. 监控访问情况

   # Check for unauthorized access attempts
   docker compose logs mcp-server | grep "Unauthorized"
   

5. 隔离网络

   • 将 ChromaDB 保持在私有网络中
   • 仅将 MCP 服务暴露到公共互联网

---

测试

本地测试

# Health check
curl http://localhost:3000/health

# MCP tools list
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# ChromaDB heartbeat
curl http://localhost:3000/api/v2/heartbeat

远程测试（启用身份验证）

# MCP endpoint (Bearer token)
curl -X POST https://your-server.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# MCP endpoint (Bearer token)
curl -X POST "https://your-server.com/mcp" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# ChromaDB REST API
curl https://your-server.com/api/v2/heartbeat \
  -H "Authorization: Bearer YOUR_TOKEN"

# Swagger UI (browser)
https://your-server.com/docs  # send Authorization: Bearer YOUR_TOKEN header

---

故障排除

ChromaDB 连接失败

# Check if ChromaDB is running
curl http://localhost:8000/api/v2/heartbeat

# Start ChromaDB with Docker
# WARNING: ChromaDB has no built-in authentication — do not publish on routable interface.
# Bind to loopback only (127.0.0.1:8000:8000). Use MCP server as the authenticated gateway.
docker run -d -p 127.0.0.1:8000:8000 chromadb/chroma:1.5.9

# Check MCP server logs
docker compose logs mcp-server

MCP 服务无响应

# Check logs
docker compose logs mcp-server

# Check port conflicts
lsof -i :3000

# Restart services
docker compose restart

Claude Desktop 连接问题

1. 重启 Claude Desktop
2. 确认 URL 包含 /mcp 路径
3. 确认传输类型为 streamableHttp（而非 sse）
4. 如果已启用身份验证，请检查令牌
5. 对于自定义连接器：确保 Tailscale Funnel 处于启用状态

本地网络上的 TLS 握手超时

如果你从与服务器相同的本地网络连接，并使用 Tailscale Funnel HTTPS：

问题：在同一网络中访问 https://your-server.ts.net 时，TLS 握手因超时而失败。

根本原因：当同一局域网中的客户端尝试通过公共 Funnel 域名连接时，Tailscale Funnel 的 TLS 终止存在问题。

解决方案：改用本地网络直接连接，而非 Tailscale HTTPS：

# Remove existing configuration
claude mcp remove chromadb

# Add with local IP address
claude mcp add chromadb --transport http \
  http://192.168.x.x:8080/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

# Or use hostname if DNS resolves
claude mcp add chromadb --transport http \
  http://server-hostname:8080/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

验证：

# Test local network connection
curl http://192.168.x.x:8080/health

# Should return: {"status":"ok","service":"chroma-remote-mcp",...}

注意：外部客户端应继续使用 Tailscale Funnel HTTPS。此问题仅影响与服务器位于同一局域网中的客户端。

身份验证错误（401）

# Verify MCP_AUTH_TOKEN is set
docker compose exec mcp-server env | grep MCP_AUTH_TOKEN

# Test without token (should fail with 401)
curl -X POST https://your-server.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Test with correct token (should succeed)
curl -X POST https://your-server.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

---

开发

从源代码构建

# Clone repository
git clone https://github.com/meloncafe/chromadb-remote-mcp.git
cd chromadb-remote-mcp

# Install dependencies
yarn install

# Development mode (auto-reload)
yarn dev

# Build TypeScript
yarn build

# Type check
yarn type-check

测试

项目包含基于 Docker 的端到端验证集成测试：

# Run all tests (starts services, runs tests, cleans up)
yarn test

# Run tests and keep containers running for debugging
yarn test:keep

# Manual test script with options
./scripts/test.sh --help

集成测试覆盖范围：

• ✅ 健康检查端点
• ✅ 身份验证（Authorization: Bearer MCP_AUTH_TOKEN；OAuth 2.1 / OIDC 多提供方）
• ✅ MCP 协议（tools/list、tools/call）
• ✅ ChromaDB REST API 代理
• ✅ 集合 CRUD 操作
• ✅ 速率限制
• ✅ 未授权访问处理

单元测试：

# Run unit tests
yarn test:unit

# Run with watch mode
yarn test:unit:watch

# Run with coverage
yarn test:unit:coverage

# Run all tests (unit + integration)
yarn test:all

单元测试覆盖范围：

• ✅ 身份验证实用工具（时序安全比较、缓冲区操作）
• ✅ 输入验证（集合名称、文档 ID、元数据）
• ✅ 数据处理（响应格式化、JSON 序列化）
• ✅ 错误消息格式化

详细的测试策略请参阅 __tests__/README.md。

代码质量与覆盖率

本项目使用 Codecov 跟踪代码覆盖率并分析测试。

Docker 开发

本地构建与测试

# Build for local testing (single platform, loads to Docker)
yarn docker:build:local

# Or with script directly
./scripts/build.sh --platform linux/amd64 --load

# Test the built image
docker run -p 3000:3000 \
  -e MCP_AUTH_TOKEN=test123 \
  devsaurus/chromadb-remote-mcp:latest

多平台构建

# Build for all platforms (amd64, arm64)
yarn docker:build

# Build with custom version
./scripts/build.sh --version 1.2.3

# Build with custom repository
./scripts/build.sh --repo myuser/my-mcp --version dev

推送到 Docker Hub

# Push latest tag
yarn docker:push

# Push specific version
VERSION=1.2.3 yarn docker:push

# Or with script directly
./scripts/build.sh --version 1.2.3 --push

# With custom repository
DOCKER_REPO=myuser/my-mcp ./scripts/build.sh --version 1.2.3 --push

Docker 脚本的环境变量：

export DOCKER_REPO=myuser/my-mcp       # Docker repository
export VERSION=1.2.3                    # Image version tag
export DOCKER_USERNAME=myuser           # For push authentication
export DOCKER_PASSWORD=mytoken          # Docker Hub token

开发脚本

所有开发脚本都位于 scripts/ 中：

脚本	用途	用法
build.sh	构建并推送 Docker 镜像	./scripts/build.sh --help
test.sh	运行集成测试	./scripts/test.sh --help
install.sh	一键安装	curl ... | bash

快速开发工作流：

# 1. Make code changes
vim src/index.ts

# 2. Test locally
yarn dev

# 3. Run integration tests
yarn test

# 4. Build Docker image
yarn docker:build:local

# 5. Test Docker image
docker-compose up

# 6. If all good, build multi-platform and push
./scripts/build.sh --version 1.2.3 --push

项目结构

chromadb-remote-mcp/
├── .github/
│   ├── ISSUE_TEMPLATE/       # GitHub issue templates
│   └── workflows/            # GitHub Actions (publish-release, security-scan, chromadb-version-check.yml)
├── scripts/
│   ├── build.sh             # Docker build and push script (multi-platform)
│   ├── test.sh              # Integration test runner
│   └── install.sh           # One-command installation
├── src/
│   ├── index.ts             # Main server entry point
│   ├── chroma-tools.ts      # MCP tool definitions and handlers
│   └── types.ts             # TypeScript type definitions
├── docker-compose.yml       # Production (prebuilt image)
├── docker-compose.dev.yml   # Development (builds from source)
├── Dockerfile               # MCP server Docker image
├── .env.example             # Environment variables template
├── package.json             # Node.js dependencies
├── tsconfig.json            # TypeScript configuration
├── SECURITY.md              # Security policy
├── CONTRIBUTING.md          # Contribution guidelines
├── CODE_OF_CONDUCT.md       # Code of conduct
├── CHANGELOG.md             # Version history
├── CHANGELOG.ko.md          # Version history (Korean)
└── LICENSE                  # MIT license

---

v2.2.3 发行说明 — CVE-2026-45829 安全加固

⚠️ 重大变更 — 从 v2.2.2 或更早版本升级的运维人员必须阅读本节。

固定 ChromaDB 镜像版本（R4）

现在，所有 docker-compose*.yml 文件都将 chromadb/chroma 固定为版本 1.5.9@sha256:...。 版本 1.0.0–1.5.8 存在 CVE-2026-45829（ChromaToast，CVSS 10.0） 漏洞， 该漏洞可通过恶意嵌入函数配置在未经身份验证的情况下实现 RCE。请勿降低固定版本。

CI 工作流（.github/workflows/chromadb-version-check.yml）会在任何 docker-compose 文件引用漏洞版本范围内的版本时导致构建失败。

移除开发环境的默认放行行为（R1，重大变更）

此前，在非生产环境中启动服务器时，如果未设置 MCP_AUTH_TOKEN 或 OIDC_ISSUERS/OIDC_PRESET，服务器仍会静默启动。此行为现已移除。

现在，除非至少配置一种身份验证方式，或明确设置 ALLOW_INSECURE_NO_AUTH=true，否则服务器将拒绝启动。

迁移：

• 生产环境：设置 MCP_AUTH_TOKEN 或配置 OIDC。
• 本地开发：在 .env 中添加 ALLOW_INSECURE_NO_AUTH=true。

ChromaDB REST 全匹配代理现默认关闭（R3，重大变更）

直通 REST 代理（此前始终挂载）现在默认禁用，除非设置 CHROMA_REST_PROXY_ENABLED=true。禁用时，所有 /api/* 请求都会返回 404。

启用后，代理会强制执行：

• DNS 重绑定防护（validateOriginHeader）—— Origin: evil.example → 403
• 身份验证（始终要求；ALLOW_INSECURE_NO_AUTH 不会绕过代理的身份验证）
• 路径过滤：禁止集合创建、修改和删除，以及嵌入函数端点（403）
• 请求体清理：POST/PUT/PATCH 请求体中的 configuration.embedding_function → 400

**迁移：**如果你依赖直接 /api/v2/* REST 透传，请设置 CHROMA_REST_PROXY_ENABLED=true 并确保已配置身份验证。

---

贡献

欢迎贡献！欢迎提交问题和拉取请求。

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 发起拉取请求

---

许可证

MIT 许可证

---

资源

• MCP 规范
• MCP TypeScript SDK
• ChromaDB 文档
• Tailscale Serve
• Tailscale Funnel
• Cloudflare Tunnel

---

支持

如果遇到任何问题或有疑问，请提交 issue。

---

v2.0.0 配置

v2.0 引入了 collection 元数据架构 v2、OAuth 2.1 OIDC、可配置的嵌入提供方，以及可选的重排器。升级指南请参阅 MIGRATION.md。

环境变量

变量	用途
EMBEDDING_PROVIDER	chromadb-default（仅支持英语，默认）/ external / openai_compatible / gemini / voyage
EMBEDDING_MODEL	提供方专用的模型 ID。存储在 collection 元数据中。
EMBEDDING_DIMENSIONS	向量维度。external 模式下必填；Gemini 支持 768/1536/3072。
EMBEDDING_API_BASE	OpenAI 兼容端点的基础 URL（Ollama / TEI / Voyage / Together / vLLM）。
EMBEDDING_API_KEY	openai_compatible 或 voyage 提供方的 Bearer 密钥。
GEMINI_API_KEY	gemini 提供方的 Google AI Studio API 密钥。
CONFIDENCE_THRESHOLD	默认的 min_score（0-1）。工具参数优先。
RERANKER_API_BASE	OpenAI 兼容的 /rerank 端点。重排器采用故障软化策略。
RERANKER_API_KEY	重排器的可选 Bearer 密钥。
RERANKER_MODEL	重排器模型 ID（默认 bge-reranker-v2-m3）。
OIDC_ISSUERS	以逗号分隔的 OIDC 颁发者 URL。
OIDC_PRESET	便捷预设名称：google,github,microsoft。
OIDC_AUDIENCE	预期的 aud 声明。
OIDC_SCOPES	用于 Protected Resource Metadata 的逗号分隔作用域。
OIDC_LOG_SUB_MODE	使用 full 记录原始 sub，否则记录 SHA-256 的前 12 个字符（默认）。
MCP_AUTH_TOKEN	仅用于服务到服务 / CI / 内部脚本。 人类用户请使用 OAuth。可与 OIDC 共存——任一方式均可通过验证。
LEGACY_COLLECTION_COMPAT	设为 true 以允许对旧版 v1 collections 进行只读访问。仍会拒绝写入。

推荐的嵌入 + 重排器组合

已在韩语 RAG 工作负载上本地验证（2026-05）。按优先级选择：

优先级	嵌入	重排器	原因
优先准确度（推荐）	gemini / gemini-embedding-001 / 1536d	cohere / rerank-multilingual-v3.0	Gemini 会生成非对称的查询↔文档向量（RETRIEVAL_QUERY/RETRIEVAL_DOCUMENT，我们的测试中自身距离约为 0.21）；Cohere 能很好地重排简短的韩语问答对。
均衡成本	voyage / voyage-3 / 1024d	cohere / rerank-multilingual-v3.0	Voyage 嵌入的成本约为 Gemini 的 1/2.5，且仍为非对称向量（input_type query/document，自身距离约为 0.56）。
最低嵌入成本	openai_compatible / text-embedding-3-small / 1536d	cohere / rerank-multilingual-v3.0	托管嵌入中成本最低；对称向量处理简短韩语查询的效果较弱，因此重排器不可或缺。
可自托管 / 离线	openai_compatible（Ollama / TEI / vLLM）	TEI bge-reranker-v2-m3 或类似模型	无需外部 API；延迟取决于本地硬件。

验证运行的说明：

• Voyage rerank-2 未能重排本次测试中使用的简短韩语问答对——在你自己的语料库验证出其他结果前，韩语场景请继续将 Cohere 设为默认重排器。
• 重排器层采用故障软化策略：不设置 RERANKER_API_BASE 即可在不更改代码的情况下禁用重排。
• 设置 CONFIDENCE_THRESHOLD（或单次调用的 min_score）以过滤低相似度结果；当所有结果都被过滤时，服务会输出 confidence_gate: "no_confident_match"。

Docker Compose 片段（Gemini + Google OAuth）

services:
  mcp-server:
    image: devsaurus/chromadb-remote-mcp:2.0.0
    environment:
      EMBEDDING_PROVIDER: gemini
      EMBEDDING_MODEL: gemini-embedding-001
      EMBEDDING_DIMENSIONS: "1536"
      GEMINI_API_KEY: ${GEMINI_API_KEY}
      OIDC_PRESET: google
      OIDC_AUDIENCE: ${OIDC_AUDIENCE}  # e.g. your client_id
      CONFIDENCE_THRESHOLD: "0.55"
      RERANKER_API_BASE: "http://desktop-gpu.tail-xxxx.ts.net:8001"
      RERANKER_MODEL: bge-reranker-v2-m3

OAuth 流程

1. 配置 IdP（Google / GitHub / Microsoft），使其为与 OIDC_AUDIENCE 匹配的受众颁发令牌。
2. 设置 OIDC_PRESET=google（或为自定义 IdP 设置 OIDC_ISSUERS=...）和 OIDC_AUDIENCE=...。
3. 客户端向 /mcp 发送 Authorization: Bearer <token>。
4. 根据 RFC 9728，401 响应会包含 WWW-Authenticate: Bearer error="...", resource_metadata="<base>/.well-known/oauth-protected-resource"。
5. MCP_AUTH_TOKEN 仍可与 OAuth 同时使用，建议用于非交互式工作负载。

读取旧版 v1 集合

设置 LEGACY_COLLECTION_COMPAT=true 以允许只读访问。对 v1 集合执行写入操作（chroma_add_documents / update / delete）仍会返回 Error: Cannot write to legacy v1 collection。请参阅 MIGRATION.md。