Chromadb Remote MCP

🚀 ChromaDB远程MCP服务器

ChromaDB远程MCP服务器是一个支持流式HTTP的MCP（模型上下文协议）服务器，它为Claude等AI助手提供对ChromaDB的远程访问能力，能够让用户在移动设备和远程位置进行语义搜索和向量数据库操作。

注意：本项目采用MCP流式HTTP（2025 - 03 - 26规范），SSE传输方式已弃用。

韩语文档

🚀 快速开始

一键安装

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（推荐 - 预构建镜像）

# 下载配置文件
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

# 配置环境
cp .env.example .env
# 编辑.env文件并设置：
#   - MCP_AUTH_TOKEN（见下面的令牌生成方法）
#   - PORT（默认值：8080）
#   - CHROMA_DATA_PATH（默认值：chroma-data）

# 启动服务
docker compose up -d
# 或者：docker-compose up -d（适用于旧版本）

# 检查健康状态
curl http://localhost:8080/health

# 查看日志
docker compose logs -f

选项2：从源代码构建

# 克隆仓库
git clone https://github.com/meloncafe/chromadb-remote-mcp.git
cd chromadb-remote-mcp

# 配置环境
cp .env.example .env
# 编辑.env文件进行配置

# 使用docker-compose启动（从源代码构建镜像）
docker compose -f docker-compose.dev.yml up -d
# 或者：docker-compose -f docker-compose.dev.yml up -d（适用于旧版本）

选项3：本地开发

# 克隆并安装
git clone https://github.com/meloncafe/chromadb-remote-mcp.git
cd chromadb-remote-mcp
yarn install

# 配置环境
cp .env.example .env
# 编辑.env文件

# 构建并运行
yarn build
yarn start

生成安全令牌

对于生产环境，需要为.env文件中的MCP_AUTH_TOKEN生成安全令牌：

# 方法1：Node.js（推荐）
node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

# 方法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

✨ 主要特性

• 跨设备共享内存：所有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桌面版和移动版：在Claude桌面版中使用自定义连接器进行一次性设置，设置会自动同步到移动应用，两者自动共享同一连接。
• Claude代码版：需要使用claude mcp add CLI命令单独设置。

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

API端点

工作原理

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

优点：

• 所有客户端使用同一个向量数据库。
• 桌面版和移动版自动共享连接。
• 自托管且私密。
• 应用重启后内存持久化。
• 嵌入数据有单一事实来源。

📦 安装指南

环境变量（.env文件）

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

cp .env.example .env

认证

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

生成安全令牌：

# 方法1：Node.js（推荐 - 来自.env.example）
node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

# 方法2：OpenSSL
openssl rand -base64 32 | tr '+/' '-_' | tr -d '='

编辑.env文件：

MCP_AUTH_TOKEN=your-generated-token-here

然后重启服务：

docker compose restart
# 或者：docker-compose restart

支持的认证方法：

1. 授权头（最安全）：Authorization: Bearer TOKEN
   • 推荐用于API客户端和自动化工具。
   • 符合MCP规范。
   • 示例：curl -H "Authorization: Bearer YOUR_TOKEN"
2. X - Chroma - Token头：X-Chroma-Token: TOKEN
   • 用于ChromaDB Python/JavaScript库。
   • 与ChromaDB客户端SDK兼容。
   • 示例：client = chromadb.HttpClient(headers={"X-Chroma-Token": "TOKEN"})
3. 查询参数（默认启用）：?apiKey=TOKEN
   • Claude桌面版自定义连接器必需。
   • 支持基于浏览器的集成。
   • 默认启用（ALLOW_QUERY_AUTH=true）。
   • 若不需要，可设置ALLOW_QUERY_AUTH=false禁用。

来源头验证（DNS重绑定保护）

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

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

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

配置其他允许的来源： 如果需要允许其他Web应用程序或自定义域名，可在.env文件的ALLOWED_ORIGINS中添加它们：

# 添加其他自定义域名（Claude.ai默认已允许）
ALLOWED_ORIGINS=https://myapp.com,https://yourdomain.com

何时配置ALLOWED_ORIGINS：

• ✅ 使用Claude桌面版自定义连接器 → 无需配置（默认允许）
• ✅ 从自定义Web应用程序访问 → 添加应用程序的域名
• ✅ 远程使用Swagger UI → 添加服务器的域名
• ❌ 使用Claude代码版CLI → 不需要（无Origin头）
• ❌ 使用Python/JavaScript客户端 → 不需要（无Origin头）
• ❌ 仅进行本地开发 → 不需要（本地主机默认允许）

示例配置：

# 对于自定义Web应用程序
ALLOWED_ORIGINS=https://myapp.com,https://app.mycompany.com

# 多个自定义域名（逗号分隔，空格会被去除）
ALLOWED_ORIGINS=https://myapp.com, https://api.example.com, https://dashboard.mycompany.com

# 如果只需要Claude.ai和本地主机，留空即可
ALLOWED_ORIGINS=

注意：Claude.ai域名（https://claude.ai、https://api.anthropic.com）和本地主机始终允许，即使ALLOWED_ORIGINS为空。服务器到服务器的请求（无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：自定义连接器（推荐 - 专业版/团队版/企业版）

1. 打开Claude桌面版 → 设置 → 集成 → 自定义连接器。
2. 点击“添加自定义服务器”。
3. 输入：
   • 名称：ChromaDB
   • URL：https://your-server.com/mcp?apiKey=YOUR_TOKEN

注意：自定义连接器会自动同步到移动应用。远程访问时认证是必需的。

方法2：mcp - remote包装器（免费版/专业版用户） 如果没有自定义连接器的访问权限，可以使用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?apiKey=YOUR_TOKEN"]
    }
  }
}

编辑文件后重启Claude桌面版。

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

Claude代码版

CLI命令：

# 无认证
claude mcp add --transport http chromadb https://your-server.com/mcp

# 有认证（查询参数 - 推荐）
claude mcp add --transport http chromadb https://your-server.com/mcp?apiKey=YOUR_TOKEN

# 有认证（头信息）
claude mcp add --transport http chromadb https://your-server.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

# 验证
claude mcp list

可用工具

MCP服务器为Claude提供以下工具：

集合管理

• chroma_list_collections - 列出所有集合
• chroma_create_collection - 创建新集合
• chroma_delete_collection - 删除集合
• chroma_get_collection_info - 获取集合元数据
• chroma_get_collection_count - 获取文档数量
• chroma_peek_collection - 预览集合内容

文档操作

• chroma_add_documents - 添加带有嵌入的文档
• chroma_query_documents - 语义搜索（向量相似度）
• chroma_get_documents - 按ID或过滤器检索文档
• chroma_update_documents - 更新现有文档
• chroma_delete_documents - 删除文档

使用Python访问ChromaDB

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

Python示例

import chromadb

# HTTPS（Tailscale Funnel，公共部署）
client = chromadb.HttpClient(
    host="your-server.com",
    port=443,
    ssl=True,
    headers={
        "X-Chroma-Token": "YOUR_TOKEN"
    }
)

# 本地开发（HTTP）
client = chromadb.HttpClient(
    host="localhost",
    port=8080,
    ssl=False,
    headers={
        "X-Chroma-Token": "YOUR_TOKEN"
    }
)

# 使用示例
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文档。

📚 详细文档

部署

选项1：Tailscale VPN（推荐）

在Tailscale网络内进行安全访问：

# 启动服务
docker compose up -d

# 启用Tailscale Serve（自动生成HTTPS证书）
tailscale serve https / http://127.0.0.1:8080

# 检查状态
tailscale serve status

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

优点：

• 自动生成HTTPS证书。
• 不暴露到公共互联网。
• 加密的VPN隧道。
• 认证可选（VPN提供安全层）。

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

要使用Claude桌面版UI自定义连接器或公开共享：

# 启用Funnel（允许公共互联网访问）
tailscale funnel 8080 on
tailscale serve https / http://127.0.0.1:8080

# 验证Funnel是否启用
tailscale serve status  # 应显示 "Funnel on"

警告：这会将服务器暴露到公共互联网。必须进行认证！ 在环境中设置MCP_AUTH_TOKEN。

禁用Funnel：

tailscale funnel 8080 off

选项3：Cloudflare Tunnel

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

# 认证
./cloudflared tunnel login

# 创建隧道
./cloudflared tunnel create chroma-mcp

# 运行隧道
./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. 监控访问

# 检查未经授权的访问尝试
docker compose logs mcp-server | grep "Unauthorized"

5. 网络隔离
   • 将ChromaDB保留在专用网络中。
   • 仅将MCP服务器暴露到公共互联网。

测试

本地测试

# 健康检查
curl http://localhost:3000/health

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

# ChromaDB心跳检查
curl http://localhost:3000/api/v2/heartbeat

远程测试（带认证）

# MCP端点（Bearer令牌）
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端点（查询参数）
curl -X POST "https://your-server.com/mcp?apiKey=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 "X-Chroma-Token: YOUR_TOKEN"

# Swagger UI（浏览器）
https://your-server.com/docs?apiKey=YOUR_TOKEN

故障排除

ChromaDB连接失败

# 检查ChromaDB是否运行
curl http://localhost:8000/api/v2/heartbeat

# 使用Docker启动ChromaDB
docker run -d -p 8000:8000 chromadb/chroma:latest

# 检查MCP服务器日志
docker compose logs mcp-server

MCP服务器无响应

# 检查日志
docker compose logs mcp-server

# 检查端口冲突
lsof -i :3000

# 重启服务
docker compose restart

Claude桌面版连接问题

1. 重启Claude桌面版。
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：

# 移除现有配置
claude mcp remove chromadb

# 使用本地IP地址添加
claude mcp add chromadb --transport http \
  http://192.168.x.x:8080/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

# 或者如果DNS解析正常，使用主机名
claude mcp add chromadb --transport http \
  http://server-hostname:8080/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

验证：

# 测试本地网络连接
curl http://192.168.x.x:8080/health

# 应返回：{"status":"ok","service":"chroma-remote-mcp",...}

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

认证错误（401）

# 验证MCP_AUTH_TOKEN是否设置
docker compose exec mcp-server env | grep MCP_AUTH_TOKEN

# 无令牌测试（应返回401错误）
curl -X POST https://your-server.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# 正确令牌测试（应成功）
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}'

开发

从源代码构建

# 克隆仓库
git clone https://github.com/meloncafe/chromadb-remote-mcp.git
cd chromadb-remote-mcp

# 安装依赖
yarn install

# 开发模式（自动重新加载）
yarn dev

# 构建TypeScript
yarn build

# 类型检查
yarn type-check

测试

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

# 运行所有测试（启动服务、运行测试、清理）
yarn test

# 运行测试并保持容器运行以进行调试
yarn test:keep

# 手动测试脚本，带有选项
./scripts/test.sh --help

集成测试覆盖范围：

• ✅ 健康检查端点
• ✅ 认证（Bearer令牌、X - Chroma - Token、查询参数）
• ✅ MCP协议（tools/list、tools/call）
• ✅ ChromaDB REST API代理
• ✅ 集合CRUD操作
• ✅ 速率限制
• ✅ 未经授权的访问处理

单元测试：

# 运行单元测试
yarn test:unit

# 以监视模式运行
yarn test:unit:watch

# 运行并生成覆盖率报告
yarn test:unit:coverage

# 运行所有测试（单元 + 集成）
yarn test:all

单元测试覆盖范围：

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

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

代码质量与覆盖率

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

Docker开发

本地构建和测试

# 为本地测试构建（单平台，加载到Docker）
yarn docker:build:local

# 或者直接使用脚本
./scripts/build.sh --platform linux/amd64 --load

# 测试构建的镜像
docker run -p 3000:3000 \
  -e MCP_AUTH_TOKEN=test123 \
  devsaurus/chromadb-remote-mcp:latest

多平台构建

# 为所有平台构建（amd64、arm64）
yarn docker:build

# 自定义版本构建
./scripts/build.sh --version 1.2.3

# 自定义仓库构建
./scripts/build.sh --repo myuser/my-mcp --version dev

推送到Docker Hub

# 推送最新标签
yarn docker:push

# 推送特定版本
VERSION=1.2.3 yarn docker:push

# 或者直接使用脚本
./scripts/build.sh --version 1.2.3 --push

# 使用自定义仓库
DOCKER_REPO=myuser/my-mcp ./scripts/build.sh --version 1.2.3 --push

Docker脚本的环境变量：

export DOCKER_REPO=myuser/my-mcp       # Docker仓库
export VERSION=1.2.3                    # 镜像版本标签
export DOCKER_USERNAME=myuser           # 推送认证用户名
export DOCKER_PASSWORD=mytoken          # Docker Hub令牌

开发脚本

所有开发脚本都位于scripts/目录下：

快速开发工作流：

# 1. 进行代码更改
vim src/index.ts

# 2. 本地测试
yarn dev

# 3. 运行集成测试
yarn test

# 4. 构建Docker镜像
yarn docker:build:local

# 5. 测试Docker镜像
docker-compose up

# 6. 如果一切正常，进行多平台构建并推送
./scripts/build.sh --version 1.2.3 --push

项目结构

chromadb-remote-mcp/
├── .github/
│   ├── ISSUE_TEMPLATE/       # GitHub问题模板
│   └── workflows/            # GitHub Actions（发布版本、安全扫描、ChromaDB版本检查）
├── scripts/
│   ├── build.sh             # Docker构建和推送脚本（多平台）
│   ├── test.sh              # 集成测试运行器
│   └── install.sh           # 一键安装
├── src/
│   ├── index.ts             # 主服务器入口点
│   ├── chroma-tools.ts      # MCP工具定义和处理程序
│   └── types.ts             # TypeScript类型定义
├── docker-compose.yml       # 生产环境（预构建镜像）
├── docker-compose.dev.yml   # 开发环境（从源代码构建）
├── Dockerfile               # MCP服务器Docker镜像
├── .env.example             # 环境变量模板
├── package.json             # Node.js依赖
├── tsconfig.json            # TypeScript配置
├── SECURITY.md              # 安全策略
├── CONTRIBUTING.md          # 贡献指南
├── CODE_OF_CONDUCT.md       # 行为准则
├── CHANGELOG.md             # 版本历史
└── LICENSE                  # MIT许可证

🤝 贡献

欢迎贡献代码！请随时提交问题和拉取请求。

1. 分叉仓库。
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

💬 支持

如果遇到任何问题或有疑问，请打开一个问题。