chromadb远程mcp服务器

Name: chromadb远程mcp服务器
Author: meloncafe

作者：meloncafe7 星标更新：2025-11-24

安装使用来源：spider==github.com

项目介绍

ChromaDB 远程 MCP 服务器

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

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

韩文文档

跨平台AI记忆服务器

兼容所有主要AI平台：

Claude（桌面版、移动版、代码）
Gemini（CLI、代码辅助）
Cursor、Cline、Windsurf、VS Code Copilot
使用任何其他兼容MCP的客户端进行远程MCP连接

功能

远程MCP服务器使所有Claude客户端（桌面版、代码、移动版）能够访问同一个自托管的ChromaDB实例。

跨设备共享内存 - 所有Claude客户端使用相同的ChromaDB实例
自托管且私有 - 您的数据保留在您的基础设施上
远程访问 - 通过Tailscale或公共互联网从任何地方连接
完整的ChromaDB支持 - 通过MCP工具进行所有CRUD操作
REST API代理 - 直接通过Python/JavaScript访问ChromaDB
统一认证 - 单一令牌保护MCP和REST API端点
简单部署 - 通过Docker进行一键安装

架构

概览

┌──────────────────────────────┐      ┌──────────────┐
│   Claude Desktop + 移动版    │      │  Claude 代码 │
│  (自定义连接器 - 同步)       │      │  (CLI设置)   │
└──────────────┬───────────────┘      └──────┬───────┘
               │                             │
               │     MCP远程连接器          │
               └─────────────┬───────────────┘
                             │ HTTPS
                   ┌─────────▼──────────┐
                   │   远程MCP          │
                   │   服务器（Node.js）│
                   │                    │
                   │ • 认证网关        │
                   │ • MCP协议         │
                   │ • REST API代理    │
                   └─────────┬──────────┘
                             │
                   ┌─────────▼──────────┐
                   │     ChromaDB       │
                   │ (向量数据库)        │
                   │                    │
                   │ • 嵌入式           │
                   │ • 集合             │
                   │ • 语义搜索         │
                   └────────────────────┘

客户端如何连接：

Claude桌面版+移动版：在Claude桌面版中使用自定义连接器设置一次，并自动同步到移动应用。两者自动共享同一连接。
Claude代码：需要单独使用claude mcp add CLI命令进行设置。

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

API端点

路径	目的	客户端	认证
`/mcp`	MCP协议	Claude桌面版/代码/移动版	✅
`/api/v2/*`	ChromaDB REST API	Python	✅
`/docs`	Swagger UI	浏览器（API文档）	✅
`/openapi.json`	OpenAPI规范	API工具	✅
`/health`	健康检查	监控	❌

工作原理

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

优点：

所有客户端使用相同的向量数据库
桌面版和移动版自动共享连接
自托管且私有
应用重启后持久记忆
嵌入式数据单一来源

快速开始

一键安装

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

这将：

下载docker-compose.yml和.env.example
自动检测Docker Compose命令（docker-compose或docker compose）
自动生成安全认证令牌（可选）
配置ChromaDB数据存储位置（Docker卷、本地目录或自定义路径）
拉取Docker镜像
显示您的认证令牌和连接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 24 | 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重新绑定保护）	-	否
`ALLOW_QUERY_AUTH`	通过查询参数启用认证（`?apiKey=TOKEN`）	`true`	否

认证

重要：对于公共互联网访问（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

支持的认证方法：

授权头（最安全）：Authorization: Bearer TOKEN
- 推荐用于API客户端和自动化工具
- 符合MCP规范
- 示例：curl -H "Authorization: Bearer YOUR_TOKEN"
X-Chroma-Token头：X-Chroma-Token: TOKEN
- 用于ChromaDB Python/JavaScript库
- 与ChromaDB客户端SDK兼容
- 示例：client = chromadb.HttpClient(headers={"X-Chroma-Token": "TOKEN"})
查询参数（默认启用）：?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头）
❌ 仅本地开发 → 不需要（localhost默认允许）

示例配置：

# 对于自定义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和localhost，留空即可
ALLOWED_ORIGINS=

注意：Claude.ai域（https://claude.ai，https://api.anthropic.com）和localhost始终允许，即使ALLOWED_ORIGINS为空。服务器到服务器请求（无Origin头）始终被允许。

数据存储配置

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

Docker卷（默认）：CHROMA_DATA_PATH=chroma-data
- 由Docker管理
- 存活容器重启
- 使用docker volume ls和docker volume inspect chroma-data定位
本地目录：CHROMA_DATA_PATH=./data
- 容易备份和访问
- 存储在安装目录
自定义路径：CHROMA_DATA_PATH=/path/to/data
- 必须是绝对路径
- 适用于挂载外部存储

更改CHROMA_DATA_PATH后，重启服务：

docker compose restart

连接Claude

Claude桌面版+移动版

方法1：自定义连接器（推荐 - Pro/Team/Enterprise）

打开Claude桌面版 → 设置 → 集成 → 自定义连接器
点击“添加自定义服务器”
输入：
- 名称：ChromaDB
- URL：https://your-server.com/mcp?apiKey=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?apiKey=YOUR_TOKEN"]
    }
  }
}

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

重要：远程MCP服务器不能直接在claude_desktop_config.json中使用streamableHttp传输进行配置。您必须使用自定义连接器或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服务器代理所有Chroma