AWS SSO MCP Server

AWS リソースに AI を接続する

AWS IAM Identity Center（旧 AWS SSO）を通じて、Claude、Cursor AI などの AI アシスタントを AWS アカウントに直接接続し、AWS インフラストラクチャの管理とアクセス方法を変革しましょう。クラウドリソースにすぐにアクセスし、コマンドを実行して、自然言語で EC2 インスタンスを管理できます。

できること

✅ AWS アカウントについて AI に質問する：「すべての AWS アカウントと利用可能なロールを表示して」
✅ AWS コマンドを実行する：「本番アカウントの S3 バケットをすべて一覧表示して」
✅ EC2 インスタンスを管理する：「サーバー i-123456789 のディスク使用量を確認して」
✅ 複数アカウント構成にアクセスする：「ステージングアカウントに切り替えて、VPC を説明して」
✅ リソースを監視する：「実行中の EC2 インスタンスのステータスをすべて取得して」
✅ シェルコマンドを実行する：「SSM 経由でウェブサーバー上で『df -h』を実行して」

最適な対象

• DevOps エンジニア：複数アカウントの AWS 環境とインフラストラクチャの自動化を管理する方
• クラウドアーキテクト：複数の AWS アカウントにわたるリソース情報にすばやくアクセスする必要がある方
• 開発者：AI を通じてデプロイを確認し、AWS CLI コマンドを実行したい方
• SRE チーム：自然言語を使って AWS リソースを監視し、トラブルシューティングを行う方
• IT 管理者：EC2 インスタンスを管理し、リモートコマンドを安全に実行する方
• すべての方：会話型 AI を使って AWS を操作したい方

クイックスタート

2 分で使い始められます。

1. AWS SSO をセットアップする

AWS IAM Identity Center をセットアップします。

1. AWS アカウントで AWS IAM Identity Center を有効にします
2. ID ソースを設定します（AWS ディレクトリ、Active Directory、または外部 IdP）
3. 許可セットを設定し、ユーザーを AWS アカウントに割り当てます
4. AWS SSO のスタート URL を控えます（例：https://your-company.awsapps.com/start）

2. すぐに試す

# Set your AWS SSO configuration
export AWS_SSO_START_URL="https://your-company.awsapps.com/start"
export AWS_REGION="us-east-1"

# Start the authentication flow
npx -y @aashari/mcp-server-aws-sso login

# List your accessible accounts and roles
npx -y @aashari/mcp-server-aws-sso ls-accounts

# Execute an AWS command
npx -y @aashari/mcp-server-aws-sso exec-command \
  --account-id 123456789012 \
  --role-name ReadOnly \
  --command "aws s3 ls"

AI アシスタントに接続する

Claude Desktop ユーザー向け

Claude の設定ファイル（~/.claude/claude_desktop_config.json）に次を追加します。

{
  "mcpServers": {
    "aws-sso": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-aws-sso"],
      "env": {
        "AWS_SSO_START_URL": "https://your-company.awsapps.com/start",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

Claude Desktop を再起動すると、ステータスバーに「🔗 aws-sso」が表示されます。

その他の AI アシスタント向け

ほとんどの AI アシスタントは MCP に対応しています。サーバーをグローバルにインストールします。

npm install -g @aashari/mcp-server-aws-sso

次に、STDIO トランスポートを使用して MCP サーバーに接続するよう、AI アシスタントを設定します。

代替方法：設定ファイル

システム全体の設定には、~/.mcp/configs.json を作成します。

{
  "aws-sso": {
    "environments": {
      "AWS_SSO_START_URL": "https://your-company.awsapps.com/start",
      "AWS_REGION": "us-east-1",
      "DEBUG": "false"
    }
  }
}

代替設定キー： システムでは "aws-sso" の代わりに "@aashari/mcp-server-aws-sso" または "mcp-server-aws-sso" も使用できます。

実際の使用例

🔐 認証して確認する

AI アシスタントに次のように質問します。

• 「AWS SSO にログインして、認証状態を表示して」
• 「すべての AWS アカウントと、引き受けられるロールを一覧表示して」
• 「AWS にまだ認証されているか確認して」
• 「アクセス権のある AWS アカウントを表示して」

🛠️ AWS コマンドを実行する

AI アシスタントに次のように質問します。

• 「ReadOnly ロールを使って、本番アカウントの S3 バケットをすべて一覧表示して」
• 「us-west-2 リージョンで実行中の EC2 インスタンスをすべて表示して」
• 「ステージング AWS アカウントの VPC を説明して」
• 「アカウント 123456789012 の RDS データベースのステータスを取得して」

🖥️ EC2 インスタンスを管理する

AI アシスタントに次のように質問します。

• 「EC2 インスタンス i-1234567890abcdef0 のディスク使用量を確認して」
• 「Systems Manager 経由でウェブサーバー上で『uptime』を実行して」
• 「本番環境のインスタンス i-abc123 で『systemctl status nginx』を実行して」
• 「すべてのアプリケーションサーバーのメモリ使用量を取得して」

🔍 インフラストラクチャを監視する

AI アシスタントに次のように質問します。

• 「開発アカウントの Lambda 関数をすべて一覧表示して」
• 「us-east-1 の CloudFormation スタックを表示して」
• 「ロードバランサーのヘルスを確認して」
• 「ALARM 状態の最新の CloudWatch アラームを取得して」

🔄 マルチアカウント操作

AI アシスタントに次のように尋ねてください。

• 「AdminRole を使用してアカウント 987654321098 に切り替え、すべてのセキュリティグループを一覧表示して」
• 「ステージングアカウントと本番アカウントの実行中のインスタンスを比較して」
• 「すべての AWS アカウントのバックアップポリシーを確認して」
• 「セキュリティアカウントの IAM ユーザーを監査して」

{}

{
  "launchBrowser": false
}

{}

{}

{
  "accountId": "123456789012", 
  "roleName": "ReadOnly",
  "command": "aws s3 ls"
}

{
  "accountId": "123456789012",
  "roleName": "AdminRole",
  "command": "aws ec2 describe-instances --query 'Reservations[*].Instances[*].[InstanceId,State.Name,InstanceType]' --output table",
  "region": "us-west-2"
}

{
  "instanceId": "i-0a69e80761897dcce",
  "accountId": "123456789012",
  "roleName": "InfraOps",
  "command": "uptime && df -h && free -m"
}

トランスポートモード

このサーバーは、さまざまな統合シナリオに対応する 2 つのトランスポートモードをサポートしています。

STDIO トランスポート（MCP クライアントのデフォルト）

• stdin/stdout を介した従来のサブプロセス通信です
• ローカルの AI アシスタントとの統合（Claude Desktop、Cursor AI）に最適です
• パイプベースの通信を使用して、MCP プロトコルを直接やり取りします

# Run with STDIO transport (default for AI assistants)
TRANSPORT_MODE=stdio npx @aashari/mcp-server-aws-sso

# Using npm scripts (after installation)
npm run mcp:stdio

HTTP トランスポート（サーバーモードのデフォルト）

• Server-Sent Events（SSE）を使用する最新の HTTP ベースのトランスポートです
• 複数の同時接続をサポートします
• ウェブベースの統合や開発に適しています
• デフォルトではポート 3000 で実行されます（PORT 環境変数で設定可能です）
• エンドポイント：https://localhost:3000/mcp
• ヘルスチェック：https://localhost:3000/

# Run with HTTP transport (default when no CLI args)
TRANSPORT_MODE=http npx @aashari/mcp-server-aws-sso

# Using npm scripts (after installation)
npm run mcp:http

# Test with MCP Inspector
npm run mcp:inspect

環境変数

トランスポート設定：

• TRANSPORT_MODE：stdio または http に設定します（デフォルト：サーバーモードでは http、MCP クライアントでは stdio）
• PORT：HTTP サーバーのポート（デフォルト：3000）
• DEBUG：デバッグログを有効にします（デフォルト：false）

AWS 設定：

• AWS_SSO_START_URL：AWS IAM Identity Center の開始 URL（例：https://your-org.awsapps.com/start）
• AWS_SSO_REGION または AWS_REGION：SSO 認証に使用する AWS リージョン（例：us-east-1）
• AWS_PROFILE：AWS プロファイル名（任意、CLI との互換性のため）

利用可能なツール

MCP を介して AI アシスタントと統合すると、次のツールを利用できます。

認証ツール

• aws_sso_login：AWS SSO デバイス認証フローを開始します

  • パラメーター：launchBrowser（任意、ブール値、デフォルト：true）
  • 認証のためにブラウザーを自動的に開きます
  • デバイス認証コードフローを処理します
  • 後続の操作に備えてトークンをキャッシュします

• aws_sso_status：現在の認証ステータスを確認します

  • パラメーターは不要です
  • セッションの詳細と有効期限を返します
  • キャッシュされたトークンの有効性を確認します

アカウント管理ツール

• aws_sso_ls_accounts：アクセス可能なすべての AWS アカウントとロールを一覧表示します
  • パラメーターは不要です
  • アカウント ID、名前、メールアドレス、利用可能なロールを表示します
  • 使用できるアカウントとロールを把握するのに不可欠です

コマンド実行ツール

• aws_sso_exec_command：SSO 認証情報を使用して AWS CLI コマンドを実行します

  • 必須：accountId、roleName、command
  • 任意：region
  • 一時認証情報を自動的に取得してキャッシュします
  • 任意の AWS CLI コマンドをサポートします

• aws_sso_ec2_exec_command：SSM を介して EC2 インスタンス上でシェルコマンドを実行します

  • 必須：instanceId、accountId、roleName、command
  • 任意：region
  • SSH アクセスは不要です（AWS Systems Manager を使用します）
  • インスタンスに SSM Agent がインストールされている必要があります

CLI コマンド

すべてのツールは、kebab-case の CLI コマンドとしても利用できます。詳細については --help を実行してください（例：mcp-aws-sso login --help）。

• login：AWS SSO で認証します（--no-launch-browser）。例：mcp-aws-sso login。
• status：認証状態を確認します（オプションなし）。例：mcp-aws-sso status。
• ls-accounts：アカウントとロールを一覧表示します（オプションなし）。例：mcp-aws-sso ls-accounts。
• exec-command：AWS CLI コマンドを実行します（--account-id、--role-name、--command、--region）。例：mcp-aws-sso exec-command --account-id 123456789012 --role-name ReadOnly --command "aws s3 ls"。
• ec2-exec-command：EC2 でシェルコマンドを実行します（--instance-id、--account-id、--role-name、--command、--region）。例：mcp-aws-sso ec2-exec-command --instance-id i-0a69e80761897dcce --account-id 123456789012 --role-name InfraOps --command "uptime"。

mcp-aws-sso login

mcp-aws-sso login --no-launch-browser

mcp-aws-sso exec-command \
  --account-id 123456789012 \
  --role-name ReadOnly \
  --command "aws s3 ls"

mcp-aws-sso exec-command \
  --account-id 123456789012 \
  --role-name AdminRole \
  --region us-west-2 \
  --command "aws ec2 describe-instances --output table"

mcp-aws-sso ec2-exec-command \
  --instance-id i-0a69e80761897dcce \
  --account-id 123456789012 \
  --role-name InfraOps \
  --command "uptime && df -h && free -m"

トラブルシューティング

「Authentication failed」または「Token expired」

1. AWS SSO で再認証します：

   # Test your SSO configuration
   npx -y @aashari/mcp-server-aws-sso login
   

2. AWS SSO の設定を確認します：

   • AWS_SSO_START_URL が正しいことを確認します（組織の SSO ポータルである必要があります）
   • AWS_REGION が SSO のリージョン設定と一致していることを確認します

3. SSO の設定を確認します：

   • ブラウザーで SSO ポータルにアクセスできることを確認します
   • AWS アカウントの割り当てが有効であることを確認します

「Account not found」または「Role not found」

1. 利用可能なアカウントとロールを確認します：

   # List all accessible accounts
   npx -y @aashari/mcp-server-aws-sso ls-accounts
   

2. アカウント ID の形式を確認します：

   • アカウント ID は正確に 12 桁である必要があります
   • ls-accounts の出力に表示される正確なアカウント ID を使用します

3. ロールの権限を確認します：

   • 指定したロールを引き受ける権限があることを確認します
   • 権限セットに表示される正確なロール名を使用します

「AWS CLI not found」またはコマンド実行エラー

1. AWS CLI v2 をインストールします：

   • AWS CLI インストールガイドからダウンロードします
   • aws コマンドがシステムの PATH に含まれていることを確認します

2. AWS CLI を個別にテストします：

   aws --version
   aws sts get-caller-identity
   

「EC2 command failed」または「SSM connection issues」

1. EC2 インスタンスの設定を確認します：

   • インスタンスに SSM Agent がインストールされ、実行中である必要があります
   • インスタンスには AmazonSSMManagedInstanceCore ポリシーを持つ IAM ロールが必要です

2. ロールの権限を確認します：

   • 引き受けたロールには ssm:SendCommand と ssm:GetCommandInvocation の権限が必要です
   • インスタンスが実行中の状態であることを確認します

3. SSM の接続をテストします：

   # Test if instance is reachable via SSM
   npx -y @aashari/mcp-server-aws-sso exec-command \
     --account-id YOUR_ACCOUNT \
     --role-name YOUR_ROLE \
     --command "aws ssm describe-instance-information"
   

Claude Desktop の統合に関する問題

1. 設定ファイルを更新した後、Claude Desktop を再起動します
2. ステータスバーに「🔗 aws-sso」インジケーターが表示されていることを確認します
3. 設定ファイルの場所を確認します：
   • macOS：~/.claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

ヘルプの利用

問題が解決しない場合：

1. 簡単なテストコマンドを実行し、すべてが動作することを確認します
2. 同様の問題についてはGitHub の Issuesを確認します
3. エラーメッセージと設定の詳細を添えて、新しい issue を作成します

よくある質問

どのような権限が必要ですか？

AWS IAM Identity Center（SSO）の設定について：

• ID ソースが設定された AWS IAM Identity Center へのアクセス
• AWS 管理者によって割り当てられた権限セット
• 管理対象とする特定の AWS アカウントへのアクセス

SSM 経由での EC2 コマンドについて：

• 引き受けたロールには ssm:SendCommand と ssm:GetCommandInvocation の権限が必要です
• EC2 インスタンスには AmazonSSMManagedInstanceCore ポリシーを持つ IAM ロールが必要です
• 対象インスタンスに SSM Agent がインストールされ、実行中である必要があります

これを複数の AWS 組織で使用できますか？

現在、各インストールで一度にサポートされる AWS SSO 開始 URL は 1 つです。複数の組織で使用するには、次の方法があります。

• セッションごとに AWS_SSO_START_URL 環境変数を切り替える
• 異なる設定で個別のインスタンスを実行する
• 組織ごとに複数の Claude Desktop 設定を使用する

SSO 認証情報の有効期間はどのくらいですか？

• SSO トークン：通常 8～12 時間（AWS IAM Identity Center が管理）
• 一時認証情報：アカウント／ロールごとに約 1 時間
• ツールがトークンの更新と認証情報のキャッシュを自動的に処理します
• トークンの有効期限が切れると、再認証を求められます

どの AI アシスタントで使用できますか？

Model Context Protocol（MCP）をサポートする AI アシスタントであれば、どれでも使用できます。

• Claude Desktop（最も人気があり、十分にテストされています）
• Cursor AI（AI 搭載コードエディター）
• Continue.dev（VS Code 拡張機能）
• その他の MCP 対応クライアント

データは安全ですか？

はい。このツールはセキュリティを最優先しています。

• すべてローカルマシン上で動作します（外部サーバーは使用しません）
• ご自身の AWS SSO 認証情報を使用します（サードパーティの認証は使用しません）
• データをサードパーティに送信することはありません
• 明示的に許可したものにのみアクセスします
• 自動的に有効期限が切れる AWS 一時認証情報を使用します
• AWS の認証情報管理に関するベストプラクティスに準拠しています
• 認証情報は標準の AWS 保存場所（~/.aws/）に保存されます

AWS CLI をインストールする必要がありますか？

aws_sso_exec_command の場合： AWS コマンドを実行するには AWS CLI v2 が必要です。

その他のツールの場合： AWS CLI は不要です。認証（aws_sso_login）、ステータス確認（aws_sso_status）、アカウント一覧表示（aws_sso_ls_accounts）は AWS CLI なしで動作します。

aws_sso_ec2_exec_command の場合： 不要です。Systems Manager 経由で AWS SDK を直接使用します。

AWS CLI プロファイルと併用できますか？

このツールは AWS IAM Identity Center を直接使用し、独自の認証情報キャッシュを管理します。AWS CLI プロファイルは必須ではありませんが、併用できます。

• ツールは認証情報を ~/.aws/sso/cache/（AWS の標準保存場所）に保存します
• 必要に応じて、他の AWS ツールとの互換性のために AWS_PROFILE を設定できます
• このツールは AWS CLI プロファイルの設定に依存せずに動作します

AWS SSO と AWS IAM Identity Center の違いは何ですか？

同じサービスです。AWS SSO は 2022 年に AWS IAM Identity Center に名称変更されました。このツールはどちらの名称にも対応しています。

• コードやドキュメントにある「AWS SSO」は AWS IAM Identity Center を指します
• 開始 URL の形式は変わりません：https://your-org.awsapps.com/start
• 名称にかかわらず、機能はすべて同じです

TOON 形式とは何ですか？

TOON（Token-Oriented Object Notation）は、大規模言語モデル向けに最適化された出力形式です。

• JSON よりコンパクトです（AI にデータを送信する際のトークン数を削減できます）
• 人が読める形式を保ちます
• 利用可能な場合は自動的に使用され、必要に応じて JSON にフォールバックします
• 詳細はこちら：@toon-format/toon

ログはどこに保存されますか？

デバッグログは ~/.mcp/data/@aashari.mcp-server-aws-sso.[session-id].log に書き込まれます。

セッションごとに固有のログファイルが作成されます。DEBUG=true を設定すると、デバッグログが有効になります。

# AWS SSO: Command Result

**Account/Role:** 123456789012/ReadOnly
**Region:** us-east-1 (Default: ap-southeast-1)

## Command

	aws s3 ls

## Output

	2023-01-15 08:42:53 my-bucket-1
	2023-05-22 14:18:19 my-bucket-2
	2024-02-10 11:05:37 my-logs-bucket

*Executed: 2025-05-19 06:21:49 UTC*

# ❌ AWS SSO: Command Error

**Account/Role:** 123456789012/ReadOnly
**Region:** us-east-1 (Default: ap-southeast-1)

## Command

	aws s3api get-object --bucket restricted-bucket --key secret.txt output.txt

## Error: Permission Denied
The role `ReadOnly` does not have permission to execute this command.

## Error Details

	An error occurred (AccessDenied) when calling the GetObject operation: Access Denied

### Troubleshooting

#### Available Roles
- AdminAccess
- PowerUserAccess
- S3FullAccess

Try executing the command again using one of the roles listed above that has appropriate permissions.

*Executed: 2025-05-19 06:17:49 UTC*

API のレスポンスが 10KB を超えると、次のメッセージとともに出力が切り詰められます。

[Response truncated for AI consumption. Full response logged to: /path/to/log/file.log]

これにより、AI アシスタントが扱いやすいサイズのレスポンスを受け取れる一方、開発者はログファイルで出力全体を確認できます。

技術的な詳細

アーキテクチャ

このサーバーは、次の 5 層のクリーンなアーキテクチャを採用しています。

1. CLI 層（src/cli/）：Commander.js を使用したコマンドラインインターフェース
2. ツール層（src/tools/）：Zod の検証スキーマを使用した MCP ツール定義
3. コントローラー層（src/controllers/）：ビジネスロジックとオーケストレーション
4. サービス層（src/services/）：外部 API とのやり取り（AWS SDK）
5. ユーティリティ層（src/utils/）：共有ユーティリティ（ログ記録、設定、キャッシュ、フォーマット）

主な依存関係

• @modelcontextprotocol/sdk v1.23.0：MCP プロトコルの実装
• @aws-sdk/client-sso v3.893.0：AWS SSO API クライアント
• @aws-sdk/client-ssm v3.893.0：EC2 コマンド用の AWS Systems Manager
• @toon-format/toon v2.0.1：トークン効率の高い出力フォーマット
• zod v4.1.13：実行時の型検証
• commander v14.0.2：CLI フレームワーク

ログ記録

デバッグログは次の場所に書き込まれます：~/.mcp/data/@aashari.mcp-server-aws-sso.[session-id].log

環境変数で DEBUG=true を設定すると、デバッグログが有効になります。

キャッシュ

• SSO トークン：~/.aws/sso/cache/ にキャッシュされます（AWS の標準の場所）
• 一時的な認証情報：アカウントとロールの組み合わせごとに 1 時間キャッシュされます
• アカウント情報：リクエストごとに最新の情報を取得します（永続的なキャッシュはありません）

開発

# Clone repository
git clone https://github.com/aashari/mcp-server-aws-sso.git
cd mcp-server-aws-sso

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode with HTTP transport
npm run dev:http

# Run with STDIO transport (for MCP client testing)
npm run dev:stdio

# Run with MCP Inspector (visual debugging)
npm run mcp:inspect

# Run tests
npm test

# Run tests with coverage
npm test:coverage

# Lint code
npm run lint

# Format code
npm run format

利用可能な npm スクリプト

• npm run build - TypeScript を JavaScript にコンパイルします
• npm run mcp:stdio - STDIO トランスポートで実行します
• npm run mcp:http - HTTP トランスポートで実行します
• npm run mcp:inspect - デバッグ用に MCP Inspector で実行します
• npm test - Jest テストを実行します
• npm run lint - ESLint を実行します
• npm run format - Prettier でコードをフォーマットします

要件

• Node.js：バージョン 18.0.0 以降
• AWS CLI：バージョン 2.x（aws_sso_exec_command にのみ必要）
• AWS IAM Identity Center：設定済みで、アクセス可能であること
• オペレーティングシステム：macOS、Linux、または Windows

バージョン履歴

v3.0.1（現行）

• npm ci での picomatch 依存関係の競合を修正
• 大規模な API レスポンスの切り詰めに対応し、生のレスポンスのログ記録を強化
• AWS SSO のログイン手順に関する AI 向けガイダンスを改善

v3.0.0

• 破壊的変更：registerTool API を備えた @modelcontextprotocol/sdk v1.23.0 に刷新
• Node.js のバージョン指定を追加（Node 22.14.0 との互換性）
• ログ記録とエラー処理を強化

v2.0.0

• 破壊的変更：AWS CLI の実行と認証情報のリージョン不一致に関する問題を修正
• クロスリージョン認証の処理を改善
• MCP モードで dotenv が STDIO に出力しないように変更

完全なバージョン履歴については、CHANGELOG.md をご覧ください。

コントリビューション

コントリビューションを歓迎します！お気軽に Pull Request を送信してください。大規模な変更の場合は、まず issue を作成して、変更内容についてご相談ください。

ライセンス

ISC ライセンス - 詳細については LICENSE ファイルをご覧ください。

サポート

お困りですか？サポートを受ける方法は次のとおりです。

1. 上記のトラブルシューティングのセクションを確認してください - よくある問題のほとんどは、そこで解決できます
2. GitHub リポジトリをご覧ください。ドキュメントと例を確認できます：github.com/aashari/mcp-server-aws-sso
3. 問題を報告してください：GitHub Issues
4. 機能リクエストや一般的な質問については、ディスカッションを開始してください
5. 詳細なエラー情報を確認するには、~/.mcp/data/@aashari.mcp-server-aws-sso.[session-id].log のデバッグログを確認してください

使用技術： TypeScript、MCP SDK、AWS SDK for JavaScript v3、TOON Format

AWS のワークフローに AI を取り入れたい DevOps チームのために、心を込めて作りました。