Chroma MCP サーバー

ChromaDBを用いたセマンティック検索とドキュメント管理機能を提供するモデルコンテキストプロトコル（MCP）サーバー。このサーバーにより、LLMは直感的な類似性メトリクスを用いてドキュメントコレクションに対する自然言語クエリを実行できるため、RAG（Retrieval Augmented Generation）アプリケーションに最適です。

特徴

セマンティック検索:最先端の埋め込みを使用して意味に基づいて文書を検索します
直感的な類似度メトリクス: 結果には人間に分かりやすい類似度スコア（0～100%）が含まれます
ドキュメント管理: ドキュメントとコレクションの完全なCRUD操作
豊富なメタデータのサポート:カスタムメタデータフィールドによる添付と検索
永続ストレージ: SQLite バックエンドを使用した信頼性の高いドキュメントストレージ
セキュリティ: 設定可能なアクセス制御と入力検証
エラー処理: 包括的なエラーメッセージと適切な障害回復

要件

Python 3.12以上
ChromaDB 0.4.22 以上
MCP Python SDK 1.1.2 以上
uv パッケージマネージャー (推奨) または pip

クイックスタート

# Clone the repository
git clone https://github.com/privetin/mcp-server-chroma.git
cd mcp-server-chroma

# Install with uv (recommended)
uv venv
.venv\Scripts\activate  # Windows
source .venv/bin/activate  # Unix
uv pip install -e .

# Or with pip
python -m venv .venv
.venv\Scripts\activate  # Windows
source .venv/bin/activate  # Unix
pip install -e .

# Run the server
mcp-server-chroma

Claude Desktop の統合については、「インストール」を参照してください。

建築

サーバーは以下に基づいて構築されています:

ベクターの保存と検索のためのChromaDB
サーバー実装用のMCP Python SDK
永続ストレージ用のSQLite

データフロー

ドキュメントはChromaDBのデフォルトの埋め込みモデルを使用して埋め込まれます
埋め込みとメタデータはChromaDBのSQLiteバックエンドに保存されます
クエリは同じ埋め込みモデルを通じて処理される
結果は0～100%の類似度スケールに正規化されます

コンポーネント

コレクションと文書

サーバーは主に 2 つのリソースタイプを管理します。

コレクション: 埋め込み設定が共有された関連ドキュメントのコンテナ
ドキュメント: メタデータと自動生成された埋め込みを含むテキストコンテンツ

ツール

コレクション管理

list-collections : 利用可能なすべてのコレクションを一覧表示する
create-collection : オプション設定で新しいコレクションを作成する
delete-collection : コレクションとそのドキュメントを削除する

ドキュメント操作

add-document : コンテンツとメタデータを含む新しいドキュメントを追加する
get-document : IDで特定のドキュメントを取得する
update-document : ドキュメントのコンテンツまたはメタデータを変更する
delete-document : コレクションからドキュメントを削除する
search-documents : 正規化された類似度スコアによるセマンティック検索

インストール

前提条件

Python 3.12以上
uv パッケージマネージャー (推奨) または pip

設定

リポジトリをクローンします。

git clone https://github.com/privetin/mcp-server-chroma.git
cd mcp-server-chroma

仮想環境を作成してアクティブ化します。

uv venv
# On Windows:
.venv\Scripts\activate
# On Unix:
source .venv/bin/activate

依存関係をインストールします:

uv pip install -e .

クロードデスクトップ統合

Claude Desktop 構成にサーバーを追加します。

Windows ( %APPDATA%/Claude/claude_desktop_config.json ):

{
  "mcpServers": {
    "chroma": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\mcp-server-chroma",
        "run",
        "mcp-server-chroma"
      ]
    }
  }
}

MacOS ( ~/Library/Application Support/Claude/claude_desktop_config.json ):

{
  "mcpServers": {
    "chroma": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-chroma",
        "run",
        "mcp-server-chroma"
      ]
    }
  }
}

使用例

コレクションの管理

コレクションを作成します:

Tool: create-collection
Args: {"name": "research-papers"}

コレクションの一覧:

Tool: list-collections
Args: {}

ドキュメントの操作

ドキュメントを追加します:

Tool: add-document
Args: {
  "collection": "research-papers",
  "content": "Recent advances in transformer architectures have led to significant improvements in natural language processing tasks.",
  "metadata": {
    "title": "Transformer Architectures",
    "year": 2024,
    "category": "ML"
  }
}

特定のドキュメントを取得します。

Tool: get-document
Args: {
  "collection": "research-papers",
  "document_id": "doc_123"
}

ドキュメントを更新します。

Tool: update-document
Args: {
  "collection": "research-papers",
  "document_id": "doc_123",
  "content": "Updated findings on transformer architectures show improvements in both efficiency and accuracy.",
  "metadata": {
    "title": "Transformer Architectures - Updated",
    "year": 2024,
    "category": "ML",
    "status": "updated"
  }
}

ドキュメントを検索:

Tool: search-documents
Args: {
  "collection": "research-papers",
  "query": "What are the latest developments in transformers?",
  "n_results": 3
}

類似度スコアの理解

検索結果には、0～100% の正規化された類似度スコアが含まれます。

90-100% : ほぼ同一の内容、または非常に強い意味的一致
70～89% : 関連性が高く、意味的な類似性も強い
50-69% : 部分的に意味が重複し、中程度の関連性がある
30～49% : 多少関連しているが、意味的なつながりは最小限
0～29% : 関連性がない、または意味的なつながりが非常に弱い

トラブルシューティング

よくある問題

データベース接続エラー
- データベースパスが書き込み可能であることを確認する
- 別のプロセスがデータベースを使用しているかどうかを確認する
- .chromaディレクトリを削除して再起動してみてください
メモリの問題
- 大規模なコレクションではより多くのRAMが必要になる場合があります
- より小さなバッチサイズの使用を検討する
- --log-level DEBUGでメモリ使用量を監視する
検索パフォーマンスが遅い
- 大規模なコレクションではインデックスの最適化が必要になる場合があります
- n_resultsを少なくすることを検討してください
- システムリソースの使用状況を確認する

デバッグモード

サーバーをデバッグモードで実行します。

mcp-server-chroma --log-level DEBUG

ヘルプの取得

ChromaDBのドキュメントを確認する
GitHubで問題を開く
MCPコミュニティのディスカッションに参加する

発達

テストの実行

テストスイートを実行します。

pytest -v

カバレッジ付きで実行:

pytest --cov=chroma tests/

デバッグ

デバッグには、MCP インスペクターを使用します。

# Install the inspector
npm install -g @modelcontextprotocol/inspector

# Run the server with inspector
mcp-inspector uv --directory /path/to/mcp-server-chroma run mcp-server-chroma

検査官は以下を提供します:

リアルタイムのリクエスト/レスポンス監視
ツールテストインターフェース
パフォーマンスメトリック
エラー追跡

エラー処理

サーバーは、一般的なシナリオに対して詳細なエラーメッセージを提供します。

コレクション名またはIDが無効です
欠落または不正な形式の文書
データベース接続の問題
無効な検索パラメータ
認証/承認の失敗

セキュリティに関する考慮事項

すべてのパラメータの入力検証
設定可能なアクセス制御
ファイルパスの安全な取り扱い
インジェクション攻撃に対する保護
レート制限のサポート
セキュアエラーメッセージ

構成

データベースの場所

カスタムデータベースパスを設定します。

mcp-server-chroma --db-path /path/to/db

デフォルト: サーバーディレクトリ内の.chroma

環境変数

CHROMA_DB_PATH : データベースの場所を上書きする
CHROMA_LOG_LEVEL : ログの詳細度を設定する (デフォルト: INFO)
CHROMA_MAX_CONNECTIONS : データベース接続プールのサイズ（デフォルト: 10）

貢献

リポジトリをフォークする
機能ブランチを作成する
変更を加える
新しい機能のテストを追加する
プルリクエストを送信する

詳細については、貢献ガイドラインをお読みください。

ライセンス

MITライセンス

本ソフトウェアおよび関連ドキュメントファイル (以下「本ソフトウェア」) のコピーを入手したすべての人物は、以下の条件に従い、本ソフトウェアを無制限に扱う権利 (使用、コピー、変更、統合、公開、配布、サブライセンス、および/または販売する権利を含みますが、これに限定されません) および本ソフトウェアの提供を受けた人物が同様の行為を行うことを許可する権利を無償で付与されます。

上記の著作権表示およびこの許可通知は、ソフトウェアのすべてのコピーまたは大部分に含めるものとします。

本ソフトウェアは「現状有姿」で提供され、明示的または黙示的を問わず、商品性、特定目的への適合性、非侵害性を含むがこれらに限定されない、いかなる種類の保証も付与されません。いかなる場合においても、著作者または著作権者は、契約違反、不法行為、またはその他の行為にかかわらず、本ソフトウェア、本ソフトウェアの使用、またはその他の取り扱いに起因または関連して発生するいかなる請求、損害、またはその他の責任についても責任を負わないものとします。