gws-admin-mcp

gws-admin-mcp

AI エージェント（Cursor、Claude Desktop、または任意の MCP クライアント）に安全な Google Workspace 管理コンソールを提供する、ローカルの Model Context Protocol（MCP）サーバーです。ドメイン全体の委任が設定されたサービスアカウントを通じて Admin SDK（Directory、Reports、Groups Settings）と通信するため、「90 日間ログインしていないユーザーは誰ですか？」や「Finance グループのメンバーは誰ですか？」といった質問にエージェントが回答できます。また、明示的に許可した場合に限り、変更を行うこともできます。

MCP client ──stdio──► gws-admin-mcp ──service account JWT (impersonates an admin)──► admin.googleapis.com / groupssettings.googleapis.com

すべてお使いのマシン上で動作します。サードパーティサービスもテレメトリーもなく、Google API 呼び出し自体を除き、データがノートパソコンの外部に送信されることはありません。

安全モデル

このサーバーは、操作するエージェントが誤りを犯す可能性を前提としています。3 つの保護層があります。

1. デフォルトでは読み取り専用です。 初期状態では、読み取りツール 17 個のみが登録されます。書き込みツールは実行時のチェックで隠されているのではなく、ツール一覧に存在しないため、エージェントは呼び出せません。変更を行うには、--allow-write（または GWS_ADMIN_ALLOW_WRITE=1）を指定してサーバーを起動する必要があります。
2. 破壊的な呼び出しには確認ゲートがあります。 書き込みを有効にしていても、元に戻せない操作（users_delete、groups_delete、orgunits_delete、role_assignment_delete、モバイルデバイスのワイプ操作、ChromeOS の登録解除）は、呼び出しに "confirm": true が含まれていない限り拒否されます。エージェントは、破壊的な操作の意図をもう一度明示する必要があります。
3. 監査ログ。 すべてのツール呼び出しは、パスワードとシークレットを秘匿化したうえで、~/.config/gws-admin-mcp/audit.log（モード 600）に JSON Lines 形式で追記されます。必要な場合は GWS_ADMIN_AUDIT=0 で無効にできます。

推奨パターン：読み取り専用のインスタンスを常時稼働させ、変更作業を行う期間だけ、書き込みを有効にした 2 つ目のインスタンスを起動します。

ツール（合計 40 個、読み取り専用モードでは 17 個）

領域	読み取り専用ツール	書き込みツール（--allow-write が必要）
ユーザー	users_list、users_get	users_create、users_update、users_suspend、users_unsuspend、users_reset_password、users_make_admin、users_move_ou、users_delete*
グループ	groups_list、groups_get、groups_list_members	groups_create、groups_update、groups_delete*、groups_add_member、groups_remove_member、groups_update_member
組織部門	orgunits_list、orgunits_get	orgunits_create、orgunits_update、orgunits_delete*
ロール	roles_list、role_assignments_list	role_assignment_create、role_assignment_delete*
ドメイン／顧客	domains_list、customer_get	—
デバイス	devices_list_mobile、devices_list_chromeos	devices_action_mobile、devices_action_chromeos、devices_move_chromeos
レポート	reports_activities（監査ログ）、reports_usage_user、reports_usage_customer	—
グループ設定	groupsettings_get	groupsettings_update

* 破壊的操作 — 呼び出しに "confirm": true を指定する必要があります（デバイスツールではワイプ／登録解除操作のみ）。

リスト取得ツールは maxResults の上限まで自動的にページネーションを行います。また、users_list は Admin SDK の検索構文全体をサポートしています（orgUnitPath='/Sales'、isAdmin=true、email:jdoe* など）。

要件

• Node.js >= 20
• Google Workspace ドメインの特権管理者アクセス権（ドメイン全体の委任を許可するため）
• Google Cloud プロジェクト（無料 — Admin SDK の利用料金はかかりません）

Google Cloud のセットアップ

Workspace の特権管理者になりすますためにサーバーが使用するキーを持つ、サービスアカウントが必要です。手順は 2 通りあります。

方法 A — スクリプトを使用（gcloud が必要）

gcloud auth login [email protected]
scripts/setup-service-account.sh [email protected] your-project-id

このスクリプトは、プロジェクトの作成または再利用、Admin SDK API と Groups Settings API の有効化、サービスアカウントの作成、キーと設定の ~/.config/gws-admin-mcp/ への書き込みを行います。また、最後の手動手順（以下の手順 5 — Google はこの部分の API を提供していません）に必要なクライアント ID とスコープ文字列を表示します。

パス B — 手動（Cloud コンソール）

1. console.cloud.google.com でプロジェクトを作成します （または、管理ツール専用の既存プロジェクトを再利用します）。
2. API を有効にします：Admin SDK API と Groups Settings API （［API とサービス］→［ライブラリ］）。
3. サービスアカウントを作成します（［IAM と管理］→［サービス アカウント］→［作成］）。 プロジェクトレベルの IAM ロールは必要ありません。権限はすべて、次の手順で付与する委任によって得られます。
4. サービスアカウントのJSON キーを作成し（［キー］タブ→［鍵を追加］→［JSON］）、~/.config/gws-admin-mcp/service-account.json として保存して、chmod 600 を実行します。
5. ドメイン全体の委任を付与します。この手順は見落としがちです。
   • サービスアカウントの OAuth 2 クライアント ID（長い数字で、サービスアカウントの詳細ページに表示されています）をコピーします。
   • Admin コンソール（admin.google.com）で、 *［セキュリティ］→［アクセスとデータの管理］→［API の制御］→［ドメイン全体の委任］→［新規追加］*を選択します。
   • クライアント ID を貼り付け、次のスコープリストをカンマ区切りの 1 行として正確に貼り付けます。

https://www.googleapis.com/auth/admin.directory.user,https://www.googleapis.com/auth/admin.directory.group,https://www.googleapis.com/auth/admin.directory.group.member,https://www.googleapis.com/auth/admin.directory.orgunit,https://www.googleapis.com/auth/admin.directory.rolemanagement,https://www.googleapis.com/auth/admin.directory.domain.readonly,https://www.googleapis.com/auth/admin.directory.customer.readonly,https://www.googleapis.com/auth/admin.directory.device.mobile,https://www.googleapis.com/auth/admin.directory.device.chromeos,https://www.googleapis.com/auth/admin.reports.audit.readonly,https://www.googleapis.com/auth/admin.reports.usage.readonly,https://www.googleapis.com/auth/apps.groups.settings

6. サーバーが偽装する管理者を指定します。 ~/.config/gws-admin-mcp/config.json を作成します。

{
  "delegatedAdmin": "[email protected]",
  "customerId": "my_customer"
}

delegatedAdmin は、ドメインのスーパー管理者である必要があります。my_customer は、その管理者自身の組織を参照します。

環境変数は設定ファイルより優先されます：GOOGLE_SA_KEY（キーのパス）、DELEGATED_ADMIN、CUSTOMER_ID、GWS_ADMIN_CONFIG_DIR（別の設定ディレクトリ）。.env.example を参照してください。

ビルドと検証

npm install
npm run build
node dist/cli.js doctor

doctor はキーを確認し、委任トークンを発行して、ユーザー、ドメイン、ロール、監査レポート API に対するサンプル読み取りを実行します。4 項目すべてが PASS と表示されるはずです。その後、必要に応じて次を実行します。

npm run smoke   # spawns the real server over stdio, checks tool registration + live reads

MCP クライアントの設定

Cursor（~/.cursor/mcp.json）

読み取り専用 — 推奨されるデフォルト設定です。

{
  "mcpServers": {
    "gws-admin": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/gws-admin-mcp/dist/cli.js", "serve"]
    }
  }
}

書き込みを有効にする場合（慎重に使用してください。できれば、切り替えて有効にする 2 つ目のエントリとして設定します）。

{
  "mcpServers": {
    "gws-admin-write": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/gws-admin-mcp/dist/cli.js", "serve", "--allow-write"]
    }
  }
}

Claude Desktop（claude_desktop_config.json）

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

{
  "mcpServers": {
    "gws-admin": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/gws-admin-mcp/dist/cli.js", "serve"]
    }
  }
}

編集後にクライアントを再起動してください。gws-admin サーバーに、ツールが 17 個（読み取り専用）または 40 個（書き込み有効）表示されるはずです。

トラブルシューティング

症状	原因／対処方法
トークン発行時に unauthorized_client が表示される	ドメイン全体の委任が付与されていない、クライアント ID が間違っている、またはスコープリストにサーバーが要求するすべてのスコープが含まれていません。上記のスコープ文字列全体を、サービスアカウントの OAuth2 クライアント ID に対して再度貼り付けてください。付与内容が反映されるまで数分かかることがあります。
Service-account key not found at ... が表示される	JSON キーを ~/.config/gws-admin-mcp/service-account.json に置くか、GOOGLE_SA_KEY にそのパスを設定してください。
DELEGATED_ADMIN ... is not set が表示される	config.json に delegatedAdmin を追加するか、DELEGATED_ADMIN 環境変数を設定してください。
403 Not Authorized to access this resource/api が表示される	偽装されたユーザーがスーパー管理者ではないか、Cloud プロジェクトで Admin SDK API が有効になっていません。
Groups Settings の呼び出しで 404 が返される	プロジェクトで Groups Settings API が有効になっていません（Admin SDK とは別の API です）。
クライアントに書き込みツールが表示されない	想定どおりの動作です。--allow-write または GWS_ADMIN_ALLOW_WRITE=1 を指定してサーバーを起動してください。
削除／消去の呼び出しで Refused: ... destructive/irreversible が返される	想定どおりの動作です。"confirm": true を指定して呼び出し直してください。
起動時にクライアントでサーバーが失敗と表示される	ターミナルで node dist/cli.js doctor を実行してください。失敗したチェックの詳細が表示されます。また、MCP 設定の args パスが絶対パスであることを確認してください。

セキュリティに関する注意事項

• サービスアカウントキーは、組織全体に対する権限を持つスーパー管理者になりすまします。 service-account.json はドメイン管理者のパスワードと同様に扱ってください。Git に含めず （このリポジトリの .gitignore では、キー ファイル、.env、および config.json はすでに除外されています）、権限を chmod 600 に設定し、 定期的にローテーションしてください。
• キーの監査と無効化を容易にするため、このサービスアカウント専用の Cloud プロジェクトを 使用してください。
• 常設のインスタンスは読み取り専用にしてください。実際に変更する場合に限り、別のインスタンスで 書き込みを有効にし、作業後は無効にしてください。

ライセンスと購入

このリポジトリはソース公開であり、オープンソースではありません。スーパー管理者の認証情報を 預ける前に、すべてのコードを読んで監査できるよう、コードは公開されていますが、使用には ライセンスが必要です。

• ライセンスを購入する（$34）： antchoutine.gumroad.com/l/gws-admin-mcp — 永続ライセンスで、書き込み対応の完全版とアップデートが含まれます。
• **無料で試す：**読み取り専用版（17 個のツール、変更を行うコードなし）は npm で gws-admin-mcp として公開されています。

正確な条件については、LICENSE をご覧ください（再配布およびホスト型サービスとしての 提供は禁止されています）。