MongoDB MCP Server

MongoDB MCP サーバー

Claude が MongoDB データベースとやり取りできるようにする Model Context Protocol（MCP）サーバーです。この実装により、Claude は会話から直接、クエリ、集計、データ操作（CRUD）、データベース管理など、幅広い MongoDB 操作を実行できます。

概要

この MongoDB MCP サーバーは、Model Context Protocol を実装し、Claude と MongoDB データベースをつなぐ橋渡しをします。標準化されたインターフェースを通じて Claude が MongoDB コマンドを実行できるようにすることで、会話から直接、データを分析、管理、操作できます。

機能

• 包括的な MongoDB 操作：ドキュメントのクエリ（find、findOne）、集計（aggregate）、ドキュメント数のカウント（count）、個別の値の取得（distinct）、データのサンプリング（sample）を実行できます。
• データ操作：ドキュメントの挿入（insertOne、insertMany）、更新（updateOne、updateMany）、削除（deleteOne、deleteMany）ができます。
• データベース管理：データベースの一覧表示（listDatabases）、コレクションの一覧表示（listCollections）、コレクションの削除（dropCollection）ができます。
• クエリ分析：集計パイプラインの実行計画を取得できます（explain）。
• 柔軟なデータベース選択：各操作の対象データベースを指定できます（デフォルトはDEFAULT_DATABASEです）。
• 安全な接続：認証情報に環境変数を使用して MongoDB に接続します。
• 簡単な統合：MCP システムを通じて Claude Desktop または Cursor で使用できます。

インストール

前提条件

• Node.js（v14 以降を推奨）
• MongoDB インスタンス（ローカルまたは Atlas）へのアクセス
• Claude Desktop または Cursor アプリケーション

セットアップ

1. このリポジトリをクローンします（フォークした場合は、ryakerをユーザー名に置き換えてください）。

   git clone [email protected]:ryaker/mongodb-mcp-server.git
   # または、HTTPS を使用する場合
   # git clone https://github.com/ryaker/mongodb-mcp-server.git
   cd mongodb-mcp-server
   

2. 依存関係をインストールします。

   npm install
   

3. Claude Desktop または Cursor を設定します。

   • MCP の設定項目を見つけます。Cursor では、通常 Settings > Extensions > Model Context Protocol にあります。Claude Desktop では、config.json ファイル内にある場合があります。
   • このサーバーのエントリを追加し、mongo-mcp-server.js ファイルへの正しい絶対パスを指定して、必要な環境変数を設定します。

   設定例（必要に応じてパスを調整してください）：

   {
     "mcpServers": {
       "mongo-custom-server": { // このキーには、内容がわかる名前を付けられます
         "command": "node",
         "args": ["/Volumes/Dev/localDev/MCPServers/CustomMongo_clean/mongo-mcp-server.js"], // <-- このパスが正しいことを確認してください！
         "env": {
           "MONGODB_URI": "mongodb+srv://your_username:your_password@your_cluster.mongodb.net/?retryWrites=true&w=majority", // <-- MongoDB の接続文字列
           "DEFAULT_DATABASE": "YourDefaultDbName" // <-- 任意：デフォルトのデータベースを設定
         }
       }
     }
   }
   

   • 重要： プレースホルダーのMONGODB_URIを、実際の MongoDB 接続文字列に置き換えてください。URI で指定するユーザーに、実行する操作に必要な権限があることを確認してください。
   • DEFAULT_DATABASEの設定は任意です。設定すると、ツール呼び出しのdatabaseパラメーターで上書きされない限り、操作はこのデータベースを対象とします。

4. Claude Desktop または Cursor を再起動して、新しい MCP サーバーを読み込みます。

ツールリファレンス

このサーバーは以下のツールを公開します。ほとんどのツールでは、対象データベースを指定するために任意のdatabaseパラメーターを使用できます。指定しない場合は、環境変数で設定したDEFAULT_DATABASEが使用されます。

クエリと読み取り

1. aggregate：MongoDB の集計パイプラインを実行します。
   • collection (string, required)：コレクション名。
   • pipeline (array, required)：集計パイプラインのステージ。
   • database (string, optional)：対象のデータベース。
2. sample：ランダムなサンプルドキュメントを取得します。
   • collection (string, required)：コレクション名。
   • count (number, optional, default: 5, max: 10)：サンプリングするドキュメント数。
   • database (string, optional)：対象のデータベース。
3. explain：集計パイプラインの実行計画を取得します。
   • collection (string, required)：コレクション名。
   • pipeline (array, required)：集計パイプラインのステージ。
   • database (string, optional)：対象のデータベース。
4. find：クエリに一致するドキュメントを検索します。
   • collection (string, required)：コレクション名。
   • filter (object, optional, default: {})：クエリフィルター。
   • projection (object, optional, default: {})：含める、または除外するフィールド。
   • limit (number, optional, default: 10, max: 100)：返すドキュメントの最大数。
   • sort (object, optional, default: {})：ソート条件。
   • database (string, optional)：対象のデータベース。
5. findOne：クエリに一致する単一のドキュメントを検索します。
   • collection (string, required)：コレクション名。
   • filter (object, required)：クエリフィルター。
   • projection (object, optional, default: {})：含める、または除外するフィールド。
   • database (string, optional)：対象のデータベース。
6. count：クエリに一致するドキュメント数を数えます。
   • collection (string, required)：コレクション名。
   • filter (object, optional, default: {})：クエリフィルター。
   • database (string, optional)：対象のデータベース。
7. distinct：フィールドの重複しない値を取得します。
   • collection (string, required)：コレクション名。
   • field (string, required)：フィールド名。
   • filter (object, optional, default: {})：クエリフィルター。
   • database (string, optional)：対象のデータベース。

データ操作（書き込み／削除）

8. insertOne：単一のドキュメントを挿入します。
   • collection (string, required)：コレクション名。
   • document (object, required)：挿入するドキュメント。
   • database (string, optional)：対象のデータベース。
9. insertMany：複数のドキュメントを挿入します。
   • collection (string, required)：コレクション名。
   • documents (array, required)：ドキュメントの配列。
   • database (string, optional)：対象のデータベース。
10. updateOne：単一のドキュメントを更新します。
    • collection (string, required)：コレクション名。
    • filter (object, required)：ドキュメントを選択するフィルター。
    • update (object, required)：更新操作（例：$set）。
    • upsert (boolean, optional, default: false)：見つからない場合に作成しますか？
    • database (string, optional)：対象のデータベース。
11. updateMany：複数のドキュメントを更新します。
    • collection (string, required)：コレクション名。
    • filter (object, required)：ドキュメントを選択するフィルター。
    • update (object, required)：更新操作。
    • database (string, optional)：対象のデータベース。
12. deleteOne：単一のドキュメントを削除します。
    • collection (string, required)：コレクション名。
    • filter (object, required)：ドキュメントを選択するフィルター。
    • database (string, optional)：対象のデータベース。
13. deleteMany：複数のドキュメントを削除します。
    • collection (string, required)：コレクション名。
    • filter (object, required)：ドキュメントを選択するフィルター。
    • database (string, optional)：対象のデータベース。

データベース／コレクション管理 14. listCollections：データベース内のすべてのコレクションを一覧表示します。 * nameOnly（ブール値、任意、デフォルト：false）：名前のみを返しますか？ * database（文字列、任意）：対象のデータベース。 15. listDatabases：サーバー上のすべてのデータベースを一覧表示します。 * nameOnly（ブール値、任意、デフォルト：true）：名前のみを返しますか？ 16. dropCollection：コレクション全体を削除します。 * collection（文字列、必須）：削除するコレクションの名前。 * confirm（ブール値、必須）：削除を確定するにはtrueを指定する必要があります。 * database（文字列、任意）：対象のデータベース。

使用例

データのクエリ：

User: Find the 5 most recent user documents in the 'users' collection.
Claude: (Calls 'find' with collection='users', limit=5, sort={createdAt: -1})

User: Show me the user document with email '[email protected]'.
Claude: (Calls 'findOne' with collection='users', filter={email: '[email protected]'})

User: How many orders were placed yesterday in the 'orders' collection in the 'sales' database?
Claude: (Calls 'count' with collection='orders', filter={orderDate: {$gte: startOfDay, $lt: endOfDay}}, database='sales')

データの集計：

User: What are the distinct product categories in the 'products' collection?
Claude: (Calls 'distinct' with collection='products', field='category')

User: Show me the total sales per month from the 'orders' collection.
Claude: (Calls 'aggregate' with collection='orders', pipeline=[...])

データの変更：

User: Insert a new user document: { name: 'Alice', email: '[email protected]' }
Claude: (Calls 'insertOne' with collection='users', document={ name: 'Alice', email: '[email protected]' })

User: Update the user with email '[email protected]' to set their status to 'active'.
Claude: (Calls 'updateOne' with collection='users', filter={email: '[email protected]'}, update={$set: {status: 'active'}})

User: Delete all log entries older than 30 days from the 'logs' collection.
Claude: (Calls 'deleteMany' with collection='logs', filter={timestamp: {$lt: thirtyDaysAgo}})

コレクションの管理：

User: List all collections in the 'staging' database.
Claude: (Calls 'listCollections' with database='staging')

User: Please drop the 'test_data' collection. Confirm deletion.
Claude: (Calls 'dropCollection' with collection='test_data', confirm=true)

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

• サーバーファイルにデータベースの認証情報を決してハードコードしないでください。また、バージョン管理にコミットしないでください。
• 接続文字列には、必ず環境変数（MONGODB_URI）を使用してください。
• この MCP サーバー専用の MongoDB ユーザーを作成し、最小権限の原則に従ってください。想定される操作に必要な権限のみを付与してください。
• セキュリティをさらに強化するため、MongoDB Atlas で IP アクセスリスト（ホワイトリスト）の使用を検討してください。

トラブルシューティング

• 接続の問題：MONGODB_URIが正しいことを確認してください。MongoDB ユーザーに必要な権限とネットワークアクセス（ファイアウォール、IP リスト）があることを確認してください。Claude Desktop／Cursor のログからサーバーログ（console.error）を確認してください。
• ツールが見つからない／動作しない：サーバーが起動しており、Claude Desktop／Cursor で正しく設定されていることを確認してください。MCP サーバーのパスが正しいことを確認してください。Claude／Cursor を再起動してください。
• 権限エラー：MongoDB ユーザーのロールと権限を確認してください。

ライセンス

MIT ライセンス

謝辞

• Model Context Protocol
• MongoDB Node.js ドライバー