MochiuWiki : SUSE, EC, PCB

MCPサーバ - MongoDB

概要

MongoDB MCP Server (mongodb/mongodb-mcp-server) は、Model Context Protocol (MCP) を通じて、
AIアシスタントがMongoDBデータベースおよびMongoDB Atlasクラスタと相互作用するための標準化されたツールインターフェースを提供するサーバである。

AIアシスタントが自然言語コマンドを通じてMongoDB操作を実行できるようにする。

Claude Desktop、Claude Code、OpenCode等の複数のMCPクライアント環境で動作する。
Windows、MacOS、Linuxの主要なOSに対応する。

このサーバを使用することにより、AIアシスタントがドキュメントのクエリ・挿入・更新・削除、集計パイプラインの実行、インデックスの管理、MongoDB Atlasクラスタの作成・管理等を自然言語による指示で自動化できるようになる。

主な機能カテゴリは以下の通りである。

  • データベース操作ツール
    ドキュメントのクエリ、挿入、更新、削除、集計パイプラインの実行
  • メタデータとスキーマツール
    データベース・コレクションの一覧表示、スキーマ推測、統計取得
  • インデックスとベクトル検索ツール
    インデックスの作成・削除、クエリの実行計画取得、ベクトル検索インデックスの作成
  • MongoDB Atlas管理ツール
    Atlasクラスタ、ユーザ、プロジェクト、アクセスリストの管理
  • 接続管理ツール
    MongoDBインスタンスへの接続と切り替え



MongoDB MCPサーバーのインストール

前提条件

MongoDB MCP Serverを使用するために必要な前提条件を以下に示す。

  • Node.jsのバージョン要件
    Node.js v20系を使用する場合は、バージョン 20.19.0 以上が必要
    Node.js v22系を使用する場合は、バージョン 22.12.0 以上が必要
  • npx コマンド
    npx コマンドを使用してMongoDB MCP Serverを実行するために必要。Node.jsに同梱されている。
  • MongoDB接続先
    MongoDB Atlasのクラスタ、またはローカルにインストールされたMongoDBインスタンスのいずれかが必要


npxを使用したインストール

npx コマンドを使用する場合、インストール不要でMongoDB MCP Serverを直接実行できる。
以下のコマンドを実行して、MongoDB MCP Serverを起動する。

npx -y mongodb-mcp-server


MCPクライアントの設定ファイルで指定する場合は、後述の各クライアント設定を参照すること。

Dockerを使用したインストール

DockerイメージはDocker Hubで公式に公開されており、Node.jsをインストールせずにMongoDB MCP Serverを実行できる。

基本的なDockerコマンドを以下に示す。

docker run --rm -i mongodb/mongodb-mcp-server:latest


接続文字列を指定して実行する場合は、以下のコマンドを実行する。

docker run --rm -i \
                -e MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/database" \
                mongodb/mongodb-mcp-server:latest


Atlas APIクレデンシャルを指定して実行する場合は、以下のコマンドを実行する。

docker run --rm -i \
                -e MDB_MCP_API_CLIENT_ID="your-client-id"         \
                -e MDB_MCP_API_CLIENT_SECRET="your-client-secret" \
                mongodb/mongodb-mcp-server:latest



MCPクライアントの設定

Claude Desktopの設定

Claude Desktopの設定ファイルの場所は以下の通りである。

  • Linux
    ~/.config/Claude/claude_desktop_config.json
  • MacOS
    ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows
    %APPDATA%\Claude\claude_desktop_config.json


接続文字列を使用する場合は、設定ファイルに以下の内容を追記する。

 {
   "mcpServers": {
     "mongodb": {
       "command": "npx",
       "args": ["-y", "mongodb-mcp-server"],
       "env": {
         "MDB_MCP_CONNECTION_STRING": "mongodb+srv://username:password@cluster.mongodb.net/myDatabase"
       }
     }
   }
 }


Atlas APIクレデンシャルを使用する場合は、設定ファイルに以下の内容を追記する。

 {
   "mcpServers": {
     "mongodb": {
       "command": "npx",
       "args": ["-y", "mongodb-mcp-server"],
       "env": {
         "MDB_MCP_API_CLIENT_ID": "your-atlas-service-account-id",
         "MDB_MCP_API_CLIENT_SECRET": "your-atlas-service-account-secret"
       }
     }
   }
 }


Dockerを使用する場合は、設定ファイルに以下の内容を追記する。

 {
   "mcpServers": {
     "mongodb": {
       "command": "docker",
       "args": [
         "run", "--rm", "-i",
         "-e", "MDB_MCP_CONNECTION_STRING=mongodb+srv://username:password@cluster.mongodb.net/database",
         "mongodb/mongodb-mcp-server:latest"
       ]
     }
   }
 }


設定ファイルを保存した後、Claude Desktopを再起動して設定を反映する。

Claude Codeの設定

Claude Codeでは、claude mcp add コマンドを使用してMongoDB MCP Serverを追加できる。

claude mcp add mongodb -- npx -y mongodb-mcp-server


プロジェクトの .mcp.json ファイルに設定を記述する場合は、以下の内容を記述する。

 {
   "mcpServers": {
     "mongodb": {
       "command": "npx",
       "args": ["-y", "mongodb-mcp-server"],
       "env": {
         "MDB_MCP_CONNECTION_STRING": "mongodb+srv://username:password@cluster.mongodb.net/myDatabase"
       }
     }
   }
 }


OpenCodeの設定

OpenCodeは、Go言語でBubble Tea TUIフレームワークを使用して実装されている。
セッション管理、マルチセッション対応を備え、会話履歴の保存、復元、エクスポートが可能である。

Desktop版はTauri v2ベースのネイティブアプリケーションとして実装されており、TypeScriptで実装された内部CLI、Rust + SolidJSで構築されたフロントエンドを組み合わせている。

設定ファイルの場所は以下の通りである。

  • ホームディレクトリ
    $HOME/.opencode.json
  • XDG設定ディレクトリ
    $XDG_CONFIG_HOME/opencode/.opencode.json
  • ローカルディレクトリ
    ./.opencode.json


stdioトランスポートでMongoDB MCP Serverを設定する場合は、設定ファイルに以下の内容を記述する。

 {
   "mcpServers": {
     "mongodb": {
       "type": "stdio",
       "command": "npx",
       "args": ["-y", "mongodb-mcp-server"],
       "env": {
         "MDB_MCP_CONNECTION_STRING": "mongodb+srv://username:password@cluster.mongodb.net/database"
       }
     }
   }
 }



環境変数とオプション

環境変数一覧

下表に、MongoDB MCP Serverの動作をカスタマイズするための環境変数を示す。

環境変数の一覧
環境変数 説明
MDB_MCP_CONNECTION_STRING MongoDBへの接続文字列を指定する。
MongoDB AtlasのSRV形式またはローカルMongoDB向けの標準形式が使用できる。
MDB_MCP_API_CLIENT_ID Atlas API認証に使用するサービスアカウントのクライアントIDを指定する。
MDB_MCP_API_CLIENT_SECRET Atlas API認証に使用するサービスアカウントのクライアントシークレットを指定する。
MDB_MCP_READ_ONLY 読み取り専用モードを有効または無効にする。

デフォルト値は true (読み取り専用)
書き込み操作を許可する場合は false を指定する。
MDB_MCP_LOG_PATH ログファイルの出力先ディレクトリパスを指定する。
MDB_MCP_DISABLE_EMBEDDINGS_VALIDATION ベクトル検索インデックス作成時の埋め込み検証を無効化する。
MDB_MCP_TELEMETRY テレメトリの送信を有効または無効にする。



接続文字列

MongoDB Atlasへの接続

MongoDB Atlasのクラスタに接続する場合は、SRV形式の接続文字列を使用する。

mongodb+srv://username:password@cluster.mongodb.net/database


下表に、各パラメータの説明を示す。

接続パラメータの一覧
パラメータ 説明
username MongoDBデータベースユーザ名
password MongoDBデータベースパスワード
cluster.mongodb.net MongoDB Atlasのクラスタホスト名（Atlasコンソールから確認できる）
database 接続先のデータベース名


ローカルMongoDBへの接続

ローカルにインストールされたMongoDBに接続する場合の接続文字列を以下に示す。

認証ありの場合の接続文字列を以下に示す。

mongodb://username:password@localhost:27017/database?authSource=admin


認証なしの場合の接続文字列を以下に示す。

mongodb://localhost:27017


認証ありの場合、authSource=admin パラメータで認証データベースを指定する必要がある。
SCRAM-SHA-256認証方式を使用する場合は、このパラメータを省略しないこと。


MongoDB MCPサーバーの機能

MongoDB MCP Serverは、データベース操作、メタデータ管理、インデックス・ベクトル検索、Atlas管理、接続管理の5つのカテゴリでツールを提供する。

データベース操作ツール

下表に、ドキュメントのクエリ・挿入・更新・削除、および集計に関するツールを示す。

データベース操作ツールの一覧
ツール 説明
find フィルタリングと投影を指定してコレクション内のドキュメントをクエリする。
aggregate コレクションに対して集計パイプラインを実行する。
insertOne コレクションに単一のドキュメントを挿入する。
updateOne コレクション内の単一ドキュメントを更新する。
deleteOne コレクションから単一ドキュメントを削除する。
count フィルタ条件に一致するドキュメント数をカウントする。


メタデータとスキーマツール

下表に、データベースやコレクションの情報確認、スキーマ推測に関するツールを示す。

メタデータとスキーマツールの一覧
ツール 説明
listDatabases 接続中のMongoDBインスタンスで利用可能なデータベースを一覧表示する。
listCollections 指定したデータベース内の利用可能なコレクションを一覧表示する。
collection-schema コレクション内のドキュメントを分析してスキーマを推測する。
collection-storage-size コレクションのストレージサイズを取得する。
db-stats データベースの統計情報を取得する。


インデックスとベクトル検索ツール

下表に、インデックスの管理、クエリの実行計画確認、ベクトル検索インデックスの作成に関するツールを示す。

インデックスとベクトル検索ツールの一覧
ツール 説明
collection-indexes コレクション上の全てのインデックスをリスト表示する。
ベクトル検索インデックスも含む。
create-index コレクションに新しいインデックスを作成する。
drop-index コレクションから指定したインデックスを削除する。
explain クエリの実行計画を取得してパフォーマンスを分析する。
create-vector-search-index コレクションにベクトル検索インデックスを作成する。


MongoDB Atlas管理ツール

下表に、MongoDB Atlasのクラスタ、ユーザ、プロジェクトの管理に関するツールを示す。
Atlas管理ツールを使用するには、MDB_MCP_API_CLIENT_ID および MDB_MCP_API_CLIENT_SECRET の設定が必要である。

MongoDB Atlas管理ツールの一覧
ツール 説明
atlas-list-clusters Atlasプロジェクト内のクラスタを一覧表示する。
atlas-inspect-cluster 指定したクラスタの詳細情報を取得する。
atlas-create-free-cluster 無料のMongoDBクラスタ (M0 Free Tier) を作成する。
atlas-create-access-list IPアドレスまたはCIDR範囲をアクセスリストに追加する。
atlas-create-db-user MongoDB Atlasデータベースユーザを作成する。
atlas-create-project MongoDB Atlasプロジェクトを作成する。
atlas-list-projects Atlasプロジェクトを一覧表示する。
atlas-list-db-users Atlasデータベースユーザを一覧表示する。
atlas-list-orgs Atlas組織を一覧表示する。
atlas-connect-cluster 指定したAtlasクラスタに接続する。


接続管理ツール

下表に、MongoDBインスタンスへの接続と切り替えに関するツールを示す。

接続管理ツールの一覧
ツール 説明
connect 指定した接続文字列でMongoDBインスタンスに接続する。
または、接続先を切り替える。
switch-connection 既存の接続間で切り替える。



使用例

MongoDB MCP Serverの各ツールは、AIアシスタントが自然言語の指示を受けて自動的に呼び出す。

ドキュメントのクエリ

コレクションからドキュメントを検索する場合の操作例を以下に示す。

  • usersコレクションからアクティブなユーザを検索する場合 
     # プロンプト例 :
 
 usersコレクションからステータスが "active" のユーザを全件取得してください。

  • 年齢でフィルタリングして特定フィールドのみ取得する場合 
     # プロンプト例 :
 
 productsコレクションから価格が1000円以上の商品の名前と価格だけを取得してください。


集計パイプライン

集計パイプラインを使用してデータを集計・加工する場合の操作例を以下に示す。

  • カテゴリ別に売上合計を集計する場合 
     # プロンプト例 :
 
 ordersコレクションをカテゴリ別にグループ化して、各カテゴリの売上合計を計算してください。

  • 月次レポートを生成する場合 
     # プロンプト例 :
 
 salesコレクションから2024年の月別売上を集計して、月ごとの件数と合計金額を表示してください。


Atlasクラスター管理

MongoDB Atlasのクラスタを管理する場合の操作例を以下に示す。
Atlas APIクレデンシャルが設定されている必要がある。

  • クラスタの一覧を確認する場合 
     # プロンプト例 :
 
 Atlasプロジェクトのクラスタ一覧を表示してください。

  • 無料クラスタを作成する場合 
     # プロンプト例 :
 
 "my-dev-cluster" という名前で無料のMongoDBクラスタを作成してください。



その他

セキュリティ

下表に、MongoDB MCP Serverのセキュリティに関する推奨事項を示す。

セキュリティに関する推奨事項
項目 説明
読み取り専用モード デフォルトで MDB_MCP_READ_ONLY=true が有効になっている。
書き込み操作（insertOne、updateOne、deleteOne等）を使用する場合は、
明示的に MDB_MCP_READ_ONLY=false を設定する必要がある。
認証情報の管理 接続文字列やAtlas APIキーなどの機密情報は、設定ファイルに直接記述せず、
環境変数（MDB_MCP_CONNECTION_STRING、MDB_MCP_API_CLIENT_ID、MDB_MCP_API_CLIENT_SECRET）を使用して、
管理することを推奨する。
サービスアカウントの権限設定 MongoDB AtlasのAPIアクセスに使用するサービスアカウントには、必要最小限の権限のみを付与すること。
ツールアクセス制御 MCPクライアントのツールアクセス制御機能を活用して、
AIアシスタントが使用できるツールを必要なものだけに制限することを推奨する。


トラブルシューティング

下表に、一般的なエラーと対処法を示す。

トラブルシューティング一覧
問題 原因 対処法
認証エラーが発生する 接続文字列のユーザ名またはパスワードが誤っている。
認証データベースが指定されていない。		 接続文字列を確認する。
SCRAM-SHA-256を使用する場合は、
接続文字列に authSource=admin を追加する。
接続できない (Connection refused) MongoDBがリッスンしているポート (デフォルト: 27017) が
ファイアウォールでブロックされている。
接続数の上限に達している。		 ファイアウォールの設定を確認してポート27017を開放する。
MongoDB Atlasのアクセスリストに自分のIPアドレスを追加する。
npxコマンドが見つからない Node.jsがインストールされていない。
または要件を満たすバージョンでない。		 Node.js v20.19.0以上 (v22系の場合はv22.12.0以上) をインストールする。
Atlas管理ツールが動作しない Atlas APIクレデンシャルが設定されていない。 環境変数 MDB_MCP_API_CLIENT_ID および
MDB_MCP_API_CLIENT_SECRET を設定する。
書き込み操作が拒否される 読み取り専用モードが有効になっている。 MDB_MCP_READ_ONLY=false を環境変数に設定する。


ログの設定

MongoDB MCP Serverのログを記録することにより、問題の診断や動作の確認に役立てることができる。

環境変数 MDB_MCP_LOG_PATH にログファイルの出力先ディレクトリパスを指定することで、ログが記録される。

Claude Desktopの設定ファイルでログパスを指定する場合は、以下のように設定する。

 {
   "mcpServers": {
     "mongodb": {
       "command": "npx",
       "args": ["-y", "mongodb-mcp-server"],
       "env": {
         "MDB_MCP_CONNECTION_STRING": "mongodb+srv://username:password@cluster.mongodb.net/myDatabase",
         "MDB_MCP_LOG_PATH": "/tmp/mongodb-mcp-logs"
       }
     }
   }
 }


指定したディレクトリが存在することを事前に確認すること。


「https://mochiu.net/index.php?title=MCPサーバ_-_MongoDB&oldid=14431」から取得