shield_lock
金大哥
联系我们
← 返回 MCP 目录
public公开dns本地运行

chromadb-remote-mcp

一个基于Streamable HTTP MCP协议的远程ChromaDB服务器，为Claude等AI助手提供向量数据库的远程访问能力，支持跨平台共享记忆和语义搜索。

article

README

🚀 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端点

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

工作原理

  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

| 变量 | 描述 | 默认值 | 是否必需 | | ------------------- | -------------------------------------------------------------------- | ------------------ | --------------------------- | | 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

支持的认证方法：

  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"
  1. 网络隔离
    • 将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/目录下： | 脚本 | 用途 | 使用方法 | | ------------ | ---------------------------- | --------------------------- | | build.sh | 构建并推送Docker镜像 | ./scripts/build.sh --help | | test.sh | 运行集成测试 | ./scripts/test.sh --help | | install.sh | 一键安装 | curl ... \| bash |

快速开发工作流：

# 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许可证

📚 资源

💬 支持

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

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端