ChromaDB Remote MCP Server

ChromaDB リモート MCP サーバー

Claude などの AI アシスタントに ChromaDB へのリモートアクセスを提供する、Streamable HTTP 対応の MCP（Model Context Protocol）サーバーです。モバイルデバイスや離れた場所から、セマンティック検索やベクトルデータベースの操作を行えます。

注：このプロジェクトでは MCP Streamable HTTP（2025-03-26 仕様）を使用します。SSE トランスポートは非推奨です。

韓国語ドキュメント

---

クロスプラットフォーム対応 AI メモリサーバー

主要な AI プラットフォームすべてに対応しています：

• Claude（Desktop、Mobile、Code）
• Gemini（CLI、Code Assist）
• Cursor、Cline、Windsurf、VS Code Copilot
• その他の MCP 対応クライアントでもリモート MCP を利用できます

特長

すべての Claude クライアント（Desktop、Code、Mobile）から、同じセルフホスト可能な ChromaDB インスタンスにアクセスできるリモート MCP サーバーです。

• デバイス間でメモリを共有 - すべての Claude クライアントが同じ ChromaDB インスタンスを使用します
• セルフホスト可能でプライベート - データはお客様のインフラストラクチャ内に保持されます
• リモートアクセス - Tailscale またはパブリックインターネット経由でどこからでも接続できます
• ChromaDB を完全サポート - MCP ツール経由ですべての CRUD 操作を行えます
• REST API プロキシ - Python／JavaScript から ChromaDB に直接アクセスできます
• 認証を統合 - 1 つのトークンで MCP と REST API の両方のエンドポイントを保護します
• 簡単にデプロイ - Docker で 1 コマンドでインストールできます

---

アーキテクチャ

概要

┌──────────────────────────────┐      ┌──────────────┐
│   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 で認証が必要な場合の認証トークン	-	いいえ
RATE_LIMIT_MAX	IP アドレスごとの 15 分間の最大リクエスト数	100	いいえ
ALLOWED_ORIGINS	許可するオリジンのカンマ区切りリスト（DNS リバインディング対策）	-	いいえ

認証

重要： パブリックインターネットからアクセスする場合（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 を設定します。
   • リソース識別子（通常は MCP サーバーの公開 URL）を OIDC_AUDIENCE に設定します。
   • サーバーは /.well-known/oauth-protected-resource で RFC 9728 保護リソースメタデータを公開します。
   • 401 レスポンスには、RFC 6750 に従って WWW-Authenticate: Bearer error="...", resource_metadata="..." が含まれます。

v2.0.0 で削除： X-Chroma-Token ヘッダー、および ?apiKey=／?token=／?api_key= クエリパラメーターによる認証は受け付けなくなりました。以前これらの方法を使用していたクライアントは、Authorization: Bearer に移行する必要があります。ALLOW_QUERY_AUTH 環境変数は無視されます。

Origin ヘッダーの検証（DNS リバインディング対策）

サーバーは DNS リバインディング攻撃を防ぐため、ブラウザーからのリクエストの Origin ヘッダーを検証します。このセキュリティ機能はデフォルトで有効になっており、ローカルの MCP サーバーを悪意のあるウェブサイトから保護します。

デフォルトで許可されるオリジン（常に許可）：

• localhost の各種表記：localhost、127.0.0.1、[::1]
• Claude.ai ドメイン：https://claude.ai、https://api.anthropic.com

許可するオリジンを追加で設定する：

追加のウェブアプリケーションやカスタムドメインを許可する必要がある場合は、.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 のカスタムコネクターを使用する場合 → 設定不要（デフォルトで許可されています）
• ✅ カスタムウェブアプリケーションからアクセスする場合 → アプリケーションのドメインを追加します
• ✅ 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=

注： Claude.ai ドメイン（https://claude.ai、https://api.anthropic.com）と localhost は、ALLOWED_ORIGINS が空の場合でも常に許可されます。サーバー間のリクエスト（Origin ヘッダーなし）も常に許可されます。

データストレージの設定

ChromaDB のデータは、次の 3 つの方法で保存できます。

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 Desktop + モバイル

方法 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 ラッパー（Free／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 を再起動します。

重要：リモート MCP サーバーは、streamableHttp トランスポートを使用して claude_desktop_config.json に直接設定できません。カスタムコネクターまたは 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＋コンパクター＋オブジェクトストレージ）が必要です。

常に "not implemented for local executor" ／ "unsupported for local chroma" を返すツールでシングルノードデプロイメントの LLM コンテキストを無駄にしないよう、デフォルトでは非表示になっています。

• 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 ドキュメント

すべての ChromaDB REST API エンドポイントの Swagger UI ドキュメントは、https://your-server.com/docs をご覧ください。

---

デプロイメント

オプション 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 証明書を自動的に提供します
   • ほかのデプロイ方法では、Let's Encrypt を使ってリバースプロキシ（Nginx/Caddy）を使用してください

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. Custom Connector の場合：Tailscale Funnel が有効であることを確認します

ローカルネットワークでの TLS ハンドシェイクタイムアウト

サーバーと同じローカルネットワークから接続しており、Tailscale Funnel HTTPS を使用している場合：

問題：同じネットワークから https://your-server.ts.net にアクセスすると、TLS ハンドシェイクがタイムアウトして失敗します。

根本原因：同じ LAN 上のクライアントがパブリック 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 を使用してください。この問題は、サーバーと同じ LAN 上のクライアントにのみ影響します。

認証エラー（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 プロトコル（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	1 コマンドでのインストール	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
└── 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 には、悪意のある埋め込み関数設定を介した認証前の RCE である CVE-2026-45829（ChromaToast、CVSS 10.0） の脆弱性があります。固定したバージョンを引き下げないでください。

CI ワークフロー（.github/workflows/chromadb-version-check.yml）では、脆弱性のある範囲のバージョンを参照する docker-compose ファイルがあると、ビルドが失敗します。

開発環境での認証フェイルオープンを廃止（R1、破壊的変更）

以前は、本番環境以外では MCP_AUTH_TOKEN または OIDC_ISSUERS／OIDC_PRESET を設定せずにサーバーを起動しても、警告なしで正常に起動していました。この動作は廃止されました。

少なくとも1つの認証方式を設定するか、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. リポジトリをフォークします
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

---

サポート

問題が発生した場合や質問がある場合は、イシューを作成してください。

---

v2.0.0 の設定

v2.0 では、コレクションメタデータスキーマ v2、OAuth 2.1 OIDC、設定可能な埋め込みプロバイダー、オプションの再ランキング機能が導入されます。アップグレードガイドについては、MIGRATION.md を参照してください。

環境変数

変数	用途
EMBEDDING_PROVIDER	chromadb-default（英語のみ、デフォルト）／external／openai_compatible／gemini／voyage
EMBEDDING_MODEL	プロバイダー固有のモデル ID。コレクションのメタデータに保存されます。
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	sub をそのまま記録する場合は full、それ以外の場合は SHA-256 の先頭 12 文字（デフォルト）。
MCP_AUTH_TOKEN	サービス間通信／CI／内部スクリプト専用です。 人間のユーザーには OAuth を使用してください。OIDC と併用でき、どちらの方式でも認証できます。
LEGACY_COLLECTION_COMPAT	レガシー v1 コレクションへの読み取り専用アクセスを許可する場合は true にします。書き込みは引き続き拒否されます。

推奨される埋め込み＋リランカーの組み合わせ

韓国語の 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、自己距離は約 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 と一致する audience 向けのトークンを発行するようにします。
2. OIDC_PRESET=google（またはカスタム IdP の場合は OIDC_ISSUERS=...）と OIDC_AUDIENCE=... を設定します。
3. クライアントは /mcp に Authorization: Bearer <token> を送信します。
4. 401 応答には RFC 9728 に準拠した 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 を参照してください。