mongodb-mcp-setup

MongoDB MCP サーバーのセットアップ

このスキルでは、エージェント型クライアントで使用する 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 がインストールされている必要があります
   • 認証情報やクラウドクラスターへのアクセスは不要です

これは、手順に沿って進める対話型ガイドです。エージェントはユーザーの環境を検出し、状況に合わせた手順を提示しますが、認証情報を尋ねたり、取り扱ったりすることはありません。ユーザーは手順 5 で、シェルプロファイルまたはエージェント型クライアントの設定に直接追加します。手順 3a と 3b で認証情報に言及する際は、必ずこの点をユーザーに明確に伝えてください。

手順 0：クライアントを検出する

ほかの作業を始める前に、ユーザーが実行しているエージェント型クライアントを特定します。これにより、手順 1 と手順 5 での認証情報の設定方法が決まります。

実行します。

env | grep "^CODEX_"

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

このクライアントの種類（Codex またはシェルベース）を、以降のすべての手順で引き継いでください。

手順 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 が見つかった場合 → 読み取り専用モードが有効です

一部の設定が存在する場合の対応：

• 既存のセットアップに読み取り専用を追加したい場合（認証情報はあるが、読み取り専用フラグがない）→ 手順 4 に進みます
• 認証方式を切り替えたい場合 → まず古い認証情報を削除する必要があることを説明します（Codex の場合は config.toml から、シェルベースのクライアントの場合はシェルプロファイルから）。その後、手順 2〜5 に進みます
• 認証情報を更新したい場合 → 手順 5 に進みます

重要：ユーザーが Atlas Admin API の操作（クラスターの管理、ユーザーの作成、パフォーマンスアドバイザーの利用など）を希望していて、MDB_MCP_CONNECTION_STRING しか持っていない場合は、サービスアカウントの認証情報が必要であると説明し、セットアップを案内することを提案してください。

ステップ 2：設定オプションを提示する

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

接続文字列（オプション A） — 次の場合に最適です。

• 単一クラスターへのアクセス
• 既存のデータベース認証情報を使用する
• セルフホストの MongoDB、または Atlas Admin API が不要

サービスアカウント認証情報（オプション B） — 次の場合に最適です。

• MongoDB Atlas のユーザー（推奨）
• 複数クラスターの切り替え
• Atlas Admin API へのアクセス（クラスター管理、ユーザー作成、パフォーマンス監視）

Atlas Local（オプション C） — 次の場合に最適です。

• クラウドを設定せずにローカル開発／テストを行う
• Docker を使って最速でセットアップする（認証情報は不要）

どのオプションを利用するか、ユーザーに尋ねてください。

ステップ 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:[email protected]/database
• mongodb://host:port（ローカル、認証なし）

ステップ 4（読み取り専用アクセスの判定）に進みます。

ステップ 3b：サービスアカウントのセットアップ

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

3b.1：Atlas サービスアカウントの作成を案内する

MongoDB Atlas サービスアカウントを作成するようユーザーに案内します。

詳細なドキュメント：https://www.mongodb.com/docs/mcp-server/prerequisites/

主な手順を案内します。

1. MongoDB Atlas に移動する — cloud.mongodb.com
2. ページ上部付近の ORGANIZATION セクションから、組織を選択する
3. 左側のサイドバーで 「Project Identity and Access」 に移動し、Applications → Create Service Account を選択します
4. 権限を設定する — Organization Member または Project Owner を付与します（正確な権限の対応関係についてはドキュメントを参照してください）
5. 認証情報を生成する — Client ID と Secret を作成します
   • ⚠️ Client Secret は一度しか表示されません — ページを離れる前に、すぐに保存してください
6. 両方の値を控える — ステップ 5 で Client ID と Client Secret が必要になります

3b.2：API Access List の設定

⚠️ 重要：ユーザーはサービスアカウントの API Access List に自分の 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 アクセスのみに適用され、データベース接続には影響しないため、グローバルな Network Access 設定より安全です。

ステップ 4（読み取り専用アクセスの判定）に進みます。

ステップ 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 があれば、すべての操作をそのまま利用できます

ステップ 4 と 5 はスキップし（設定不要）、ステップ 6（次のステップ）に進みます。

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

オプション A と B にのみ適用されます。オプション C の場合はステップ 6 に進んでください。

読み取り専用アクセスと読み書きアクセスのどちらを希望するか尋ねます。

• 読み書きアクセス（デフォルト）：すべてのデータにアクセスでき、変更も可能です

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

• 読み取り専用アクセス：データの読み取りのみで、変更はできません

  • 最適な用途：本番データの保護、レポート作成、コンプライアンス

読み取り専用の場合：ステップ 5 の認証情報スニペットに読み取り専用フラグを含めます。 読み書きアクセスの場合：フラグを省略します（デフォルトで読み書きアクセスになります）。

ステップ 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>"

読み取り専用が選択された場合（ステップ 4）、次も追加します。

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

Codex：同じ [mcp_servers.mongodb.env] セクションに MDB_MCP_READ_ONLY = "true" を追加します。

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

5.2: 仕上げる（シェルベースのクライアントのみ）

~/.mcp-env のアクセス権を制限します。

# adjust for windows if needed
chmod 600 ~/.mcp-env

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

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

5.3: 検証する

シェルベースのクライアント — まずプロファイルを再読み込みしてから、検証します。

source ~/.zshrc  # adjust to match the profile file
env | grep "^MDB_MCP" | sed '/^MDB_MCP_READ_ONLY=/!s/=.*/=[set]/'

Codex：

# adjust path if on 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] に置き換えた状態で表示されます。何も表示されない場合は、認証情報が保存されていることと（シェルベースのクライアントの場合は）プロファイルが再読み込みされていることを確認してください。

ステップ 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）：サービスアカウントの API Access List に IP アドレスが含まれていることを確認してください。含まれていない場合、すべての 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）を使用してください（ステップ 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 の代わりに、fish では set -x、PowerShell では $env: を使用してください