🗄️ MongoDB MCP Server for LLMS

🗄️ LLM 向け MongoDB MCP サーバー

LLM が MongoDB データベースと直接やり取りできるようにする Model Context Protocol（MCP）サーバーです。自然言語を使って、コレクションのクエリ、スキーマの確認、データ管理をシームレスに行えます。

📚 Model Context Protocol（MCP）とは？

Model Context Protocol（MCP）は、AI システムが外部のデータソースやツールに接続するための汎用的な方法を提供する、Anthropic が開発したオープン標準です。MCP は、次の間で標準化された通信チャネルを確立します。

• MCP クライアント：データを利用する Claude のような AI アシスタント（例：Claude Desktop、Cursor.ai）
• MCP サーバー：データと機能を提供するサービス（この MongoDB サーバーなど）

MCP の主なメリット：

• 汎用的なアクセス：AI アシスタントがさまざまなソースのデータをクエリするための単一のプロトコルを提供します
• 標準化された接続：認証、利用ポリシー、データ形式を一貫して処理します
• 持続可能なエコシステム：複数の LLM クライアントで動作する再利用可能なコネクターを促進します

✨ 機能

• 🔍 コレクションスキーマの確認
• 📊 ドキュメントのクエリとフィルタリング
• 📈 インデックス管理
• 📝 ドキュメント操作（挿入、更新、削除）
• 🔒 接続文字列による安全なデータベースアクセス
• 📋 包括的なエラー処理と検証

📋 前提条件

開始する前に、以下を用意してください。

• Node.js（v18 以上）
• MongoDB インスタンス（ローカルまたはリモート）
• Claude Desktop や Cursor.ai などの MCP クライアント

次のコマンドを実行して、Node.js のインストールを確認できます。

node --version  # Should show v18.0.0 or higher

🚀 クイックスタート

開始するには、MongoDB の接続 URL を確認し、次の設定を Claude Desktop の設定ファイルに追加してください。

MacOS：~/Library/Application\ Support/Claude/claude_desktop_config.json
Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "mongo-mcp",
        "mongodb://<username>:<password>@<host>:<port>/<database>?authSource=admin"
      ]
    }
  }
}

Smithery 経由でのインストール

Smithery.ai は、MCP サーバーの検索とインストールを簡単にするレジストリプラットフォームです。Smithery を使って Claude Desktop 用の MongoDB MCP Server を自動的にインストールするには：

npx -y @smithery/cli install mongo-mcp --client claude

Cursor.ai との統合

Cursor.ai で MongoDB MCP を使用するには：

1. Cursor.ai を開き、Settings > Features に移動します
2. 機能パネルで「MCP Servers」を探します
3. 次の設定で新しい MCP サーバーを追加します。
   • Name：mongodb
   • Command：npx
   • Args：mongo-mcp mongodb://<username>:<password>@<host>:<port>/<database>?authSource=admin

注：Cursor が現在サポートしている MCP ツールは、Composer の Agent 機能内でのみ使用できます。

テスト用サンドボックスのセットアップ

接続先の MongoDB サーバーがなく、サンプルのサンドボックスを作成したい場合は、次の手順に従ってください。

1. Docker Compose を使って MongoDB を起動します。

docker-compose up -d

2. テストデータをデータベースに投入します。

npm run seed

Claude Desktop の設定

次の設定を Claude Desktop の設定ファイルに追加します。

MacOS：~/Library/Application\ Support/Claude/claude_desktop_config.json
Windows：%APPDATA%/Claude/claude_desktop_config.json

ローカル開発モード：

{
  "mcpServers": {
    "mongodb": {
      "command": "node",
      "args": [
        "dist/index.js",
        "mongodb://root:example@localhost:27017/test?authSource=admin"
      ]
    }
  }
}

テスト用サンドボックスのデータ構造

シードスクリプトは、サンプルデータを含む 3 つのコレクションを作成します。

Users

• 個人情報（名前、メールアドレス、年齢）
• 座標を含むネストされた住所
• 興味・関心の配列
• 会員登録日

Products

• 商品の詳細（名前、SKU、カテゴリ）
• ネストされた仕様
• 価格と在庫情報
• タグと評価

Orders

• 商品明細を含む注文の詳細
• ユーザー参照
• 配送と支払いの情報
• ステータスの追跡

🎯 プロンプトの例

Claude で次のプロンプトを試して、機能を確認してください。

基本操作

"What collections are available in the database?"
"Show me the schema for the users collection"
"Find all users in San Francisco"

高度なクエリ

"Find all electronics products that are in stock and cost less than $1000"
"Show me all orders from the user [email protected]"
"List the products with ratings above 4.5"

インデックス管理

"What indexes exist on the users collection?"
"Create an index on the products collection for the 'category' field"
"List all indexes across all collections"

ドキュメント操作

"Insert a new product with name 'Gaming Laptop' in the products collection"
"Update the status of order with ID X to 'shipped'"
"Find and delete all products that are out of stock"

📝 利用可能なツール

サーバーは、データベースとのやり取りに次のツールを提供します。

クエリツール

• listCollections：データベース内で利用可能なコレクションを一覧表示します
• find：フィルタリングとプロジェクションを指定してドキュメントを検索します
• insertOne：コレクションに単一のドキュメントを挿入します
• updateOne：コレクション内の単一のドキュメントを更新します
• deleteOne：コレクションから単一のドキュメントを削除します

インデックスツール

• createIndex：コレクションに新しいインデックスを作成します
• dropIndex：コレクションからインデックスを削除します
• indexes：コレクションのインデックスを一覧表示します

🛠️ 開発

このプロジェクトは、次の技術を使用して構築されています。

• 型安全な開発のための TypeScript
• データベース操作のための MongoDB Node.js driver
• スキーマ検証のための Zod
• サーバー実装のための Model Context Protocol SDK

開発環境をセットアップするには、次の手順を実行します。

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

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

この MCP サーバーを MongoDB データベースで使用する場合は、次の点に注意してください。

1. 用途に必要な最小限の権限を付与した専用の MongoDB ユーザーを作成します
2. 本番環境では管理者の認証情報を絶対に使用しないでください
3. 監査のためにアクセスログを有効にします
4. コレクションに適切な読み取り／書き込み権限を設定します
5. 接続文字列のパラメーターを使ってアクセスを制限します（例：readPreference=secondary）
6. データベースへのアクセスを制限するため、IP アドレスの許可リストの使用を検討します

⚠️ 重要：データベースアクセスを設定する際は、常に最小権限の原則に従ってください。

🌐 仕組み

MongoDB MCP サーバーは、次の処理を行います。

1. 指定された接続文字列を使用して MongoDB データベースに接続します
2. MCP 仕様に準拠するツールとして MongoDB の操作を公開します
3. 型安全性とセキュリティのために Zod を使用して入力を検証します
4. クエリを実行し、構造化データを LLM クライアントに返します
5. コネクションプーリングと適切なエラー処理を管理します

すべての操作は、インジェクション攻撃などのセキュリティ問題を防ぐため、適切な検証を行ってから実行されます。

📦 デプロイ

この MCP サーバーは、次のいずれかの方法でデプロイできます。

• npx を使ってローカルで実行する（クイックスタートを参照）
• グローバル npm パッケージとして実行する：npm install -g @coderay/mongo-mcp-server
• Docker コンテナで実行する（リポジトリ内の Dockerfile を参照）
• Heroku、Vercel、AWS などのプラットフォームでサービスとして実行する

❓ トラブルシューティング

よくある問題

1. 接続エラー

   • MongoDB の接続文字列が正しいことを確認します
   • MongoDB サーバーが起動しており、アクセス可能であることを確認します
   • ネットワーク権限で接続が許可されていることを確認します

2. 認証の問題

   • ユーザー名とパスワードが正しいことを確認します
   • 認証データベースが指定されていることを確認します（通常は authSource=admin）
   • MongoDB で TLS/SSL 接続が必要かどうか確認します

3. ツール実行時の問題

   • Claude Desktop または Cursor.ai を完全に再起動します
   • 詳細なエラーメッセージをログで確認します。

     # macOS
     tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
     

4. パフォーマンスの問題

   • 頻繁にクエリを実行するフィールドに適切なインデックスを追加することを検討します
   • プロジェクションを使用して、クエリで返されるデータを制限します
   • ページネーションには limit および skip パラメーターを使用します

ヘルプの利用

問題が発生した場合は、次の方法をお試しください。

• MCP ドキュメントを確認します
• GitHub リポジトリで問題を報告します

🤝 貢献

貢献を歓迎します。お気軽にプルリクエストを送信してください。

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add some amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

📜 ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は LICENSE ファイルを参照してください。