Chromadb Remote MCP

ChromaDB远程MCP服务器

     

A. 流式HTTP MCP（模型上下文协议）服务器，为克劳德等人工智能助手提供对ChromaDB的远程访问。支持从移动设备和远程位置进行语义搜索和矢量数据库操作。

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

韩语文档

______________________________________________________________________

跨平台AI内存服务器

与所有主要AI平台兼容：

• Claude（桌面、移动、代码）
• Gemini（命令行界面、代码辅助）
• Cursor、Cline、Windsurf、VS代码复制品
• 并将远程MCP与任何其他兼容MCP的客户端一起使用

特性

远程MCP服务器，使所有Claude客户端（桌面、代码、移动）能够访问相同的自托管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中的自定义连接器设置一次，它就会自动同步到移动应用程序。两者自动共享相同的连接。
• 克劳德代码：需要使用单独的设置 claude mcp add CLI命令。

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

API终点

运作原理

1. 克劳德台式机/手机：通过自定义连接器添加MCP服务器（设备之间自动同步）
2. 克劳德代码：使用添加MCP服务器 claude mcp add CLI命令
3. 远程MCP服务器 验证请求并将MCP协议转换为ChromaDB操作
4. 色度数据库 存储和检索用于语义搜索的向量嵌入
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

生成安全令牌

对于生产使用，生成一个安全令牌 MCP_AUTH_TOKEN 在 .env:

# 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用户界面： http://localhost:8080/docs

______________________________________________________________________

配置

环境变量（.env文件）

所有配置都是通过 .env 文件。复制 .env.example 到 .env 并自定义：

cp .env.example .env

认证

重要： 对于公共互联网接入（Tailscale漏斗、Cloudflare隧道等），您 必须 集 MCP_AUTH_TOKEN 在你的 .env 文件。

生成安全令牌：

# 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

1. OAuth 2.1/OpenID连接 --推荐给人类用户。

- 集 OIDC_ISSUERS （以逗号分隔的发行者URL）或 OIDC_PRESET=google,github,microsoft. - 集 OIDC_AUDIENCE 资源标识符（通常是MCP服务器的公共URL）。 - 服务器在以下位置发布RFC 9728受保护资源元数据 /.well-known/oauth-protected-resource. - 401条回复包括 WWW-Authenticate: Bearer error="...", resource_metadata="..." 根据 RFC 6750。

在v2.0.0中删除： X-Chroma-Token 页眉和 ?apiKey= / ?token= / ?api_key= 不再接受查询参数身份验证。以前使用这些路径的客户端必须迁移到 Authorization: BearerThe ALLOW_QUERY_AUTH env-var被忽略。

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

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

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

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

配置其他允许的来源：

如果需要允许其他web应用程序或自定义域，请将它们添加到 ALLOWED_ORIGINS 在你的 .env 文件：

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

何时配置ALLOWED_ORIGINS：

• ✅ 使用Claude桌面自定义连接器→ 无需配置 （默认情况下允许）
• ✅ 从自定义web应用程序访问→ 添加应用程序的域
• ✅ 远程使用Swagger UI→ 添加服务器的域
• ❌ 使用克劳德代码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=

注： Claude.ai域名(https://claude.ai, https://api.anthropic.com)始终允许使用localhost，即使 ALLOWED_ORIGINS 是空的。始终允许服务器到服务器的请求（不带Origin标头）。

数据存储配置

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

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

- 由Docker管理 - 容器重启后幸存 - 使用 docker volume ls 和 docker volume inspect chroma-data 定位

1. 本地目录: CHROMA_DATA_PATH=./data

- 易于备份和访问 - 存储在安装目录中

1. 自定义路径: CHROMA_DATA_PATH=/path/to/data

- 必须是绝对路径 - 适用于安装外部存储

更换后 CHROMA_DATA_PATH，重新启动服务：

docker compose restart

______________________________________________________________________

连接克劳德

克劳德桌面+移动

方法1：自定义连接器（推荐-专业版/团队版/企业版）

1. 打开克劳德桌面→ 设置→ 集成→ 自定义连接器
2. 点击“添加自定义服务器”
3. 输入：

- 名称: ChromaDB - 统一资源定位符: https://your-server.com/mcp （套 Authorization: Bearer YOUR_TOKEN 在连接器的头部配置中）

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

方法2:mcp远程包装器（免费/专业用户）

如果您无法访问自定义连接器，请使用 mcp-remote 打包作为解决方法：

配置文件位置：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %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。

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

克劳德代码

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)

默认情况下隐藏，因此单节点部署不会在始终返回的工具上浪费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)

呼叫发出a [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文档。

______________________________________________________________________

部署

选项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

您的服务器现在可以在以下位置访问 https://your-machine.tailXXXXX.ts.net 您Tailnet中的所有设备。

优势：

• 自动HTTPS证书
• 没有公开的互联网曝光
• 加密VPN隧道
• 身份验证可选（VPN提供安全层）

选项2：尾部漏斗（公共互联网）

要使用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 在您的环境中。

禁用漏斗：

tailscale funnel 8080 off

选项3:Cloudflare隧道

# 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. 启用公共访问身份验证

- 集 MCP_AUTH_TOKEN 使用Tailscale漏斗或公共互联网时 - 生成强令牌： openssl rand -base64 32 | tr '+/' '-_' | tr -d '=' - 定期旋转令牌

1. 使用HTTPS

- Tailscale提供自动HTTPS证书 - 将反向代理（Nginx/Caddy）与Let's Encrypt一起用于其他部署

1. 比公共互联网更喜欢VPN

- Tailscale Serve（仅限VPN）比Funnel（公共）更安全 - 身份验证在VPN中是可选的，但对于公共访问是强制性的

1. 监控访问

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

1. 网络隔离

- 将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
docker run -d -p 8000:8000 chromadb/chroma:latest

# 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桌面连接问题

1. 重新启动克劳德桌面
2. 验证URL是否包含 /mcp 路径
3. 确认运输类型为 streamableHttp （不是 sse)
4. 检查身份验证令牌（如果已启用）
5. 对于自定义连接器：确保尾秤漏斗处于活动状态

本地网络上的TLS握手超时

如果您从与服务器相同的本地网络连接并使用Tailscale漏斗HTTPS：

问题：访问时TLS握手失败并超时 https://your-server.ts.net 来自同一网络。

根本原因：当同一局域网上的客户端尝试通过公共漏斗域连接时，Tailscale漏斗会出现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漏斗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的E2E验证的集成测试：

# 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协议（工具/列表、工具/调用）
• ✅ 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/:

快速开发工作流程：

# 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)
├── 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
└── LICENSE                  # MIT license

______________________________________________________________________

贡献

欢迎投稿！请随时提交问题和拉取请求。

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文档
• 尾秤服务
• 尾鳞片漏斗
• Cloudflare隧道

______________________________________________________________________

支持

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

______________________________________________________________________

v2.0.0配置

v2.0引入了集合元数据模式v2、OAuth 2.1 OIDC、可配置的嵌入提供程序和可选的重新登录器。看 MIGRATION.md 获取升级指南。

环境变量

推荐嵌入+重新链接组合

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

验证运行注意事项：

• 航行 rerank-2 未对简短的KR问题进行重新排序↔本测试中使用的答案对——将Cohere作为KR的重新排序默认值，直到您自己的语料库显示其他情况。
• 再粘合剂层失效柔软：离开 RERANKER_API_BASE 未设置此选项可在不更改代码的情况下禁用重新分级。
• 集 CONFIDENCE_THRESHOLD （或每次通话 min_score)删除低相似性点击；服务器发出 confidence_gate: "no_confident_match" 当每个结果都被过滤时。

Docker编写代码片段（Gemini+谷歌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 （或 OIDC_ISSUERS=... 用于自定义IdP）以及 OIDC_AUDIENCE=....
3. 客户端发送 Authorization: Bearer 到 /mcp.
4. 401条回复包括 WWW-Authenticate: Bearer error="...", resource_metadata="/.well-known/oauth-protected-resource" 根据 RFC 9728。
5. MCP_AUTH_TOKEN 与OAuth一起仍然有效——建议用于非交互式工作负载。

阅读旧版v1收藏

集 LEGACY_COLLECTION_COMPAT=true 以允许只读访问。写作(chroma_add_documents / update / delete)v1上的收藏仍然返回 Error: Cannot write to legacy v1 collection。参见 MIGRATION.md.