MongoDB MCP Server セットアップ

このスキルは、エージェンティッククライアントで使用するために MongoDB MCP サーバーを設定するプロセスをユーザーにガイドします。

概要

MongoDB MCP サーバーには認証が必要です。ユーザーには 3 つのオプションがあります：

1. 接続文字列 (オプション A): 特定クラスターへの直接接続

   • シングルクラスターのクイックセットアップ
   • MDB_MCP_CONNECTION_STRING 環境変数が必要

2. サービスアカウント認証情報 (オプション B): MongoDB Atlas Admin API アクセス

   • Atlas ユーザーに推奨 - 認証とデータアクセスを簡素化
   • Atlas Admin API へのアクセスと atlas-connect-cluster を経由した動的クラスター接続
   • 手動による DB ユーザー認証情報管理不要
   • MDB_MCP_API_CLIENT_ID と MDB_MCP_API_CLIENT_SECRET 環境変数が必要

3. Atlas Local (オプション C): Docker を使用したローカル開発

   • ローカルテストに最適 - ゼロ設定で実行可能
   • Docker で Atlas をローカル実行、Docker のインストールが必要
   • 認証情報またはクラウドクラスターアクセス不要

これはインタラクティブなステップバイステップガイドです。エージェントはユーザーの環境を検出してカスタマイズされた指示を提供しますが、認証情報の要求または処理は絶対に行いません — ユーザーは Step 5 でシェルプロフィールまたはエージェンティッククライアント設定に直接認証情報を追加します。認証情報が Step 3a および 3b に登場する際は、ユーザーにこれを明確に伝えてください。

Step 0: クライアントの検出

まず、ユーザーが実行しているエージェンティッククライアントを確認します。これが Step 1 と Step 5 での認証情報の設定方法を制御します。

実行：

env | grep "^CODEX_"

• CODEX_* 変数が存在しない → ユーザーはシェルベースクライアント(Claude、Cursor、Gemini CLI、Copilot CLI など)を実行しています。認証情報はシェルプロフィール環境変数を経由して設定します。
• CODEX_* 変数が存在する → ユーザーは Codex を実行しています。認証情報は ~/.codex/config.toml (macOS/Linux) または %USERPROFILE%\.codex\config.toml (Windows) に保存されます。シェル環境変数には保存されません。デスクトップアプリは Finder、Launchpad、または Windows スタートメニューから起動された場合、シェル環境変数を継承しません。

このクライアントタイプ(Codex 対 シェルベース)を以降のすべてのステップで使用します。

Step 1: 既存の設定を確認

認証情報が既に設定されているかどうかを確認します。

シェルベースクライアント — 現在の環境を確認：

env | grep "^MDB_MCP" | sed '/^MDB_MCP_READ_ONLY=/!s/=.*/=[set]/'

Codex — ~/.codex/config.toml (macOS/Linux) または %USERPROFILE%\.codex\config.toml (Windows) を検索：

grep -E 'MDB_MCP_(CONNECTION_STRING|API_CLIENT_ID|API_CLIENT_SECRET|READ_ONLY)' ~/.codex/config.toml 2>/dev/null | sed '/MDB_MCP_READ_ONLY/!s/[[:space:]]*=[[:space:]].*/ = "[set]"/'

解釈 (両者共通):

• MDB_MCP_CONNECTION_STRING が表示される → 接続文字列認証が設定済み
• MDB_MCP_API_CLIENT_ID と MDB_MCP_API_CLIENT_SECRET の両方が表示される → サービスアカウント認証が設定済み。いずれか一つだけ存在する場合は未完成として扱う
• MDB_MCP_READ_ONLY が表示される → 読み取り専用モードが有効

部分的な設定の処理:

• ユーザーが既存のセットアップに読み取り専用を追加したい(認証はあるが読み取り専用フラグなし) → Step 4 へスキップ
• ユーザーが認証方法を切り替えたい → 古い認証情報を削除する必要があることを説明(Codex の場合は config.toml から、シェルベースクライアントの場合はシェルプロフィールから)、その後 Step 2～5 を進める
• ユーザーが認証情報を更新したい → Step 5 へスキップ

重要: ユーザーが Atlas Admin API アクション(クラスター管理、ユーザー作成、パフォーマンスアドバイザー)を望んでいるが、MDB_MCP_CONNECTION_STRING のみを持っている場合は、サービスアカウント認証情報が必要であることを説明し、セットアップを通じてサポートすることを提案します。

Step 2: 設定オプションを提示

有効な設定が存在しない場合、オプションを提示します：

接続文字列 (オプション A) — 最適な用途：

• シングルクラスターアクセス
• 既存のデータベース認証情報
• セルフホスト MongoDB または Atlas Admin API 不要

サービスアカウント認証情報 (オプション B) — 最適な用途：

• MongoDB Atlas ユーザー (推奨)
• マルチクラスター切り替え
• Atlas Admin API アクセス(クラスター管理、ユーザー作成、パフォーマンス監視)

Atlas Local (オプション C) — 最適な用途：

• クラウドセットアップなしのローカル開発/テスト
• Docker で最速セットアップ、認証情報不要

ユーザーが進めたいオプションを尋ねます。

Step 3a: 接続文字列セットアップ

ユーザーがオプション A を選択した場合：

3a.1: 接続文字列の検索方法を説明

接続文字列の取得場所と方法を説明：

MongoDB Atlas の場合:

1. cloud.mongodb.com にアクセス
2. クラスターを選択 → Connect をクリック
3. Drivers または Shell を選択 → 接続文字列をコピー
4. <username> と <password> をデータベースユーザー認証情報に置き換え

セルフホスト MongoDB の場合:

• 接続文字列は通常、DBA またはアプリケーション設定で構成されています
• フォーマット: mongodb://username:password@host:port/database

予想されるフォーマット:

• mongodb://username:password@host:port/database
• mongodb+srv://username:password@cluster.mongodb.net/database
• mongodb://host:port (ローカル、認証なし)

Step 4 (読み取り専用アクセスの決定) へ進みます。

Step 3b: サービスアカウントセットアップ

ユーザーがオプション B を選択した場合：

3b.1: Atlas サービスアカウント作成をガイド

ユーザーに MongoDB Atlas サービスアカウントの作成を指示：

完全なドキュメント: https://www.mongodb.com/docs/mcp-server/prerequisites/

主要なステップをガイド：

1. MongoDB Atlas にナビゲート — cloud.mongodb.com
2. Access Manager → Service Accounts → Create Service Account に移動
3. 権限を設定 — Organization Member または Project Owner を付与(正確な権限マッピングについてはドキュメントを参照)
4. 認証情報を生成 — Client ID と Secret を作成
   • ⚠️ Client Secret は一度だけ表示されます — ページを離れる前に必ず保存してください
5. 両方の値をメモ — Step 5 で Client ID と Client Secret が必要になります

3b.2: API アクセスリストの設定

⚠️ 重要: ユーザーはサービスアカウントの API アクセスリストに自分の IP アドレスを追加する必要があります。そうしないと、すべての Atlas Admin API 操作が失敗します。

手順：

1. サービスアカウント詳細ページで API Access List を見つけます
2. Add Access List Entry をクリック
3. 現在の IP アドレスを追加します。可能な限り特定の IP または CIDR 範囲を使用します。
   • ⚠️ 0.0.0.0/0 は任意の IP からのアクセスを許可します — これは重大なセキュリティリスクです。 一時的なテスト時の最後の手段としてのみ使用し、その直後に削除してください。本番環境では決して使用しないでください。
4. 変更を保存

これはグローバルなネットワークアクセス設定よりも安全です。API アクセスのみに影響し、データベース接続には影響しません。

Step 4 (読み取り専用アクセスの決定) へ進みます。

Step 3c: Atlas Local セットアップ

ユーザーがオプション C を選択した場合：

3c.1: Docker インストールを確認

Docker がインストールされているか確認：

docker info

インストールされていない場合は: https://www.docker.com/get-started にリダイレクト

3c.2: セットアップ完了を確認

Atlas Local は認証情報不要 — ユーザーは開始準備完了：

• デプロイメント作成: atlas-local-create-deployment
• デプロイメント一覧表示: atlas-local-list-deployments
• すべての操作が Docker でそのまま動作

Step 4 と 5 をスキップ(設定不要)して Step 6 (次のステップ) に進みます。

Step 4: 読み取り専用対 読み書きアクセスを決定

オプション A と B のみに適用。オプション C は Step 6 へスキップ。

読み取り専用または読み書きアクセスを望むかを尋ねます：

• 読み書き(デフォルト): 完全なデータアクセス、変更が可能

  • 最適な用途: 開発、テスト、管理タスク

• 読み取り専用: データ読み取りのみ、変更不可

  • 最適な用途: 本番データ安全性、レポート作成、コンプライアンス

読み取り専用の場合: Step 5 の認証情報スニペットに読み取り専用フラグを含めます。 読み書きの場合: 省略します(デフォルトは読み書き)。

Step 5 (認証情報の設定) へ進みます。

Step 5: 認証情報の設定

認証情報の要求または処理は行いません — ユーザーが直接追加できるようにしてください。

5.1: 認証情報を追加

シェルベースクライアント — 認証情報を専用の ~/.mcp-env ファイルに保存(シェルプロフィールに直接ではなく)してから、プロフィールからソースします。これにより、デフォルトでグループ/ワールド読み取り可能なファイルから認証情報を遠ざけ、git への誤ったコミットを防ぎます。

Codex — ~/.codex/config.toml (macOS/Linux) または %USERPROFILE%\.codex\config.toml (Windows) に追加します。

ユーザーに適切なスニペットを表示：

接続文字列 (オプション A):

シェルベースクライアント (~/.mcp-env):

export MDB_MCP_CONNECTION_STRING="<paste-your-connection-string-here>"

Codex (config.toml):

[mcp_servers.mongodb.env]
MDB_MCP_CONNECTION_STRING = "<paste-your-connection-string-here>"

サービスアカウント (オプション B):

シェルベースクライアント (~/.mcp-env):

export MDB_MCP_API_CLIENT_ID="<paste-your-client-id-here>"
export MDB_MCP_API_CLIENT_SECRET="<paste-your-client-secret-here>"

Codex (config.toml):

[mcp_servers.mongodb.env]
MDB_MCP_API_CLIENT_ID = "<paste-your-client-id-here>"
MDB_MCP_API_CLIENT_SECRET = "<paste-your-client-secret-here>"

読み取り専用が選択されていた場合 (Step 4)、以下も追加:

シェルベース: ~/.mcp-env に export MDB_MCP_READ_ONLY="true" を追加。

Codex: 同じ [mcp_servers.mongodb.env] セクション内に MDB_MCP_READ_ONLY = "true" を追加。

⚠️ config.toml と ~/.mcp-env は平文で保存されます。バージョン管理にコミットしないでください。

5.2: 最終化 (シェルベースクライアントのみ)

~/.mcp-env のパーミッションを制限：

# Windows が必要な場合は調整
chmod 600 ~/.mcp-env

シェルプロフィール(例：~/.zshrc)に source ~/.mcp-env を追加します。検出されたシェルに合わせて調整(例：fish の場合: bass source ~/.mcp-env または set -x、PowerShell の場合: 代わりに .ps1 ファイルをドット-ソース)。

必要に応じて echo $SHELL を実行してシェルとプロフィールファイルを検出します。

5.3: 確認

シェルベースクライアント — まずプロフィールをリロード、その後確認：

source ~/.zshrc  # プロフィールファイルに合わせて調整
env | grep "^MDB_MCP" | sed '/^MDB_MCP_READ_ONLY=/!s/=.*/=[set]/'

Codex:

# Windows の場合はパスを調整
grep -E 'MDB_MCP_(CONNECTION_STRING|API_CLIENT_ID|API_CLIENT_SECRET|READ_ONLY)' ~/.codex/config.toml 2>/dev/null | sed '/MDB_MCP_READ_ONLY/!s/[[:space:]]*=[[:space:]].*/ = "[set]"/'

期待される出力は設定されたキーを値が [set] で隠された状態で表示します。何も表示されない場合は、認証情報が保存されており、(シェルベースクライアントの場合)プロフィールがリロードされたことを確認します。

Step 6 (次のステップ) へ進みます。

Step 6: 次のステップ

オプション A & B (接続文字列 / サービスアカウント)：

1. エージェンティッククライアントを再起動:

   • シェルベースクライアント: クライアントを完全に終了し、source <profile-file> を実行して新しい変数をロード、同じターミナルセッションからクライアントを再度開いて環境を継承するようにします。
   • Codex: 完全に終了して再起動します。ターミナルセッションは不要 — 認証情報は config.toml から取得されます。

2. MCP サーバーを確認: 再起動後、MongoDB 操作を実行して確認します。

3. ツールの使用:

   • オプション A: 直接データベースアクセスツールが利用可能
   • オプション B: さらに Atlas Admin API ツールと atlas-connect-cluster が利用可能
   • 重要 (オプション B): 自分の IP がサービスアカウントの API アクセスリストに含まれていることを確認するか、すべての API 呼び出しが失敗します

オプション C (Atlas Local)：

1. すぐに使用可能: 再起動または設定不要！

2. 次のステップ:

   • デプロイメント作成: atlas-local-create-deployment
   • デプロイメント一覧表示: atlas-local-list-deployments
   • 接続後は標準的なデータベース操作を使用

トラブルシューティング

• source 後も変数が表示されない (シェルベースクライアント): プロフィールファイルのパスを確認し、ファイルが保存されていることを確認
• クライアントが変数を取得しない: 完全な再起動(終了 + 再度開く)を実行してください。リロードのみではありません
• Codex デスクトップアプリが認証情報を取得しない: Finder、Launchpad、または Windows スタートメニューから起動されている場合、Codex はシェル環境変数を .zshrc/.zprofile/PowerShell プロフィールから継承しません。代わりに ~/.codex/config.toml (macOS/Linux) または %USERPROFILE%\.codex\config.toml (Windows) を使用してください (Step 5 参照)
• 無効な接続文字列フォーマット: フォーマットを再確認してください。mongodb:// または mongodb+srv:// で始まる必要があります
• Atlas Admin API エラー (オプション B): 自分の IP がサービスアカウントの API アクセスリストに含まれていることを確認
• 読み取り専用モードが動作しない: MDB_MCP_READ_ONLY が設定されていることを確認 — Codex の場合は [mcp_servers.mongodb.env] 下の config.toml で、シェルベースクライアントの場合は env | grep ^MDB_MCP_READ_ONLY で
• fish/PowerShell: 構文が異なります — export の代わりに set -x (fish) または $env: (PowerShell) を使用してください