Yaw Labs AWS MCP

@yawlabs/aws-mcp

ワンクリックでローカルの Yaw MCP 設定に追加され、すべての Yaw Terminal セッションで利用できるようになります。または、以下の手順で手動インストールしてください。

AI アシスタント向けの小規模な AWS MCP です。1 つのサーバー、1 つの設定エントリ、SSO の再認証機能を内蔵、1,300 種類以上のリソースタイプに対応する汎用 CRUD、ライブドキュメント検索、バッチワークフロー向けのサーバーサイドスクリプト機能を備えています。

これはAWS 公式 MCP サーバーの代替であり、補完するものではありません。どちらもあらゆる AWS API にアクセスできるため、両方を実行すると、モデルに同じ操作を行うための重複した方法を 2 つ与えることになります。（AWS も旧サーバーについて同じことを勧めており、セットアップガイドでは「AI エージェントを混乱させるツールの競合を避けるため」に削除するよう記載しています。）どちらか一方を選んでください。対応範囲は重複していますが、設計は異なります。率直に比較すると、次のとおりです。

• AWS MCP Server — AWS がホストするサーバーで、2026 年 5 月から GA となり、Agent Toolkit for AWS の一部です。AWS チームが厳選したスキル、数日前までの API カバレッジを備えたサーバーサイド Python サンドボックス（run_script）、読み取り専用のサーバーレストラブルシューティング機能（Lambda の diagnose、最近の変更、X-Ray トレースの要約）、直接の API 呼び出しと区別できる IAM 条件キー、ツールごとの CloudWatch メトリクスに強みがあります。2026 年 9 月時点で、AWS API を呼び出す汎用的な方法は run_script のみです。単一呼び出し用の call_aws ツールは削除されたため、単発の describe であっても、モデルが作成する Python スクリプトとして実行します。エンドポイントは us-east-1 と eu-central-1 で稼働します。接続方法は 2 通りあります。
  • OAuth（2026 年 7 月より）を AWS Sign-in 経由で利用します。インストールは不要です。クライアントがブラウザーを開き、エンドポイントに直接接続します。各セッションは 1 つの IAM ロールに紐付けられ、最長 12 時間更新されます。また、プリンシパルには signin:AuthorizeOAuth2Access と signin:CreateOAuth2Token が必要です。
  • SigV4 は uv で実行するローカルプロキシ（AWS のガイドにある uvx mcp-proxy-for-aws-cli@latest）経由で利用し、AWS CLI の認証情報（CLI 2.32.0 以降）で署名します。AWS はターミナルや IDE のコーディングエージェントにこの方法を推奨しており、プロキシ起動時に固定される許可リストから、呼び出しごとにプロファイルを切り替えられるのはこの方法だけです。AWS CLI 2.35.0 以降では、aws configure agent-toolkit を実行すると、エージェントの MCP 設定に SigV4 エントリ（uvx mcp-proxy-for-aws@latest）が aws-mcp というキーで書き込まれます。
• @yawlabs/aws-mcp（このサーバー）— npm からインストールし、手元の aws CLI とプロファイルを使ってローカルで実行します。npx の 1 行だけで導入でき、uv もプロキシも、ホスト型サービスへの中継も不要です。特に、aws sso login のブラウザー連携が途切れたとき（特に Windows）に SSO に再ログインしやすい点、ツール呼び出し 1 回につき AWS 操作 1 件の実行（aws_call では service、operation、params を指定するため、ホストの承認プロンプトにはスクリプトではなく操作そのものが表示されます）、ドライラン差分に対応した使いやすい CCAPI CRUD、複数リージョン・複数アカウントへのファンアウト、事前の IAM 権限チェック、バッチ処理が必要な場合に使える JS スクリプトツール（インプロセスであり、セキュリティサンドボックスではありません。ツール一覧を参照）に優れています。ライブ AWS ドキュメントの検索とページ読み込みも組み込まれているため、どちらを選んでも別のドキュメントサーバーは不要です。トピックのルーティングやスキルの検索結果はありませんが、公式サーバーの search_documentation／read_documentation と同じ範囲をカバーします。 どちらの選択肢にも確実に組み合わせられる MCP は、awslabs/mcp のサービス別サーバーです。汎用の AWS API ツールでは対応できない機能を利用できます。最もわかりやすい例は、Bedrock のエージェント型ナレッジベース検索です（補助的な設定を参照）。AWS は現在、このリポジトリの後継として Agent Toolkit for AWS を案内しています。このリポジトリは引き続き動作し、コントリビューションも受け付けていますが、一部のサーバーは非推奨、または後継に置き換えられています。汎用の AWS API サーバーもそのひとつです。追加する前に、各サーバーの README を確認してください。

このサーバーがうまく対処しようとしていることは、次の 5 つです。

1. SSO の再ログイン。 セッション中にトークンの有効期限が切れると、aws sso login はサブプロセスからブラウザーを開こうとしますが、Windows（および場合によってはそれ以外の環境）では、その受け渡しが何の通知もなく失敗します。その結果、ターミナルに切り替えて自分でコマンドを実行し、戻ってくることになります。--no-browser を使うデバイスコードフローなら、この問題を解決できます。アシスタントに短縮 URL とコードが表示されるので、一度クリックすれば完了です。（--no-browser だけでは不十分になりました。AWS CLI 2.22.0 では PKCE 認可コードフローがデフォルトになり、短縮コードが表示されなくなったため、このサーバーは --use-device-code も併用し、aws --version を一度確認することで、2.22 より前の CLI との互換性を保ちます。）長時間のワークフローを始める前に、期限切れが近い認証情報を先回りして更新する aws_refresh_if_expiring_soon もあります。AWS のホスト型サーバーは、この問題を解決するのではなく回避しています。OAuth を使う場合、MCP クライアントが独自のブラウザーサインインを実行し、トークンはそのクライアントとサーバーにひも付けられるため、マシン上のほかのものはその恩恵を受けられません。SigV4 を使う場合、AWS のトラブルシューティング表は、SSO ユーザーに aws sso login を自分で実行してから MCP クライアントを再起動するよう案内しています。こちらでは再ログインにより、CLI、SDK、およびマシン上のほかのすべてのツールが読み取る同じ ~/.aws/sso/cache トークンが更新されます。
2. あらゆる AWS API の呼び出し。 aws_call は aws CLI を直接プロキシします。サービスごとにツールを増やしたり、SDK を同梱したりすることなく、明日 AWS が追加するサービスも含め、API の全機能を一つのツールで利用できます。これは将来の話ではありません。2026 年 9 月に追加された AWS Batch の一括 cancel-jobs／terminate-jobs（CLI 2.36.44）、STS のセッショントークンサイズフィールド（2.36.45）、Elastic Beanstalk のクラスター環境（2.36.47）、"Tunnel" VPC エンドポイント（2.36.48）は、ローカルの aws CLI が対応した時点で利用でき、@yawlabs/aws-mcp のアップグレードは不要です。古い CLI では、知らない操作は送信前に拒否され、アップグレードを促すエラーが表示されます。aws_paginate はページネーションを伴う list／describe 操作を処理し、aws_multi_region は同じ操作を N 個のリージョンに並列で実行します。また、JMESPath の query パラメーターで、サーバー側でレスポンスを絞り込めます。このサーバーの 5 MB の出力上限に達するより、ずっと早くこれらのツールを活用してください。MCP ホストの制限はさらに小さく、Claude Code は 10,000 トークンで警告し、デフォルトでは 25,000 トークンを超える結果をファイルに保存します。モデルはそのファイルを読み戻す必要があります。
3. サービスをまたいだ汎用 CRUD。 aws_resource_*（ドライランのプレビュー用 aws_resource_diff を含む 7 つのツール）は AWS Cloud Control API をラップしているため、CloudFormation スキーマを持つあらゆるコントロールプレーンリソースで、同じライフサイクル（get／list／create／update／delete／status）を利用できます。Lambda 関数、S3 バケット、IAM ロール、SSM パラメーター、RDS インスタンスなど、AWS の公開リストにある 1,300 種類が対象です（すべての種類がすべての操作に対応しているわけではありません）。awaitCompletion: true を指定すると、サーバーが非同期の作成／更新／削除を終端状態までポーリングします。AWS Labs は 2026 年 3 月に独自の Cloud Control API MCP サーバーを非推奨とし、移行ガイドには、リソースの get／list／create／update／delete に対する直接の代替手段は記載されていません。後継は代わりに CloudFormation と CDK を作成します。CCAPI はコントロールプレーン専用です。データプレーンでは、DynamoDB の get-item／query と Bedrock の converse は aws_call で処理できる通常の操作です（DynamoDB の値は型付き JSON の {"S": "..."} のままです）。Lambda の呼び出しには専用ツール aws_lambda_invoke があります。aws_call では扱えない操作は 3 種類あります。位置引数の出力ファイルにレスポンス本文を書き込む操作（S3 の get-object、Bedrock の invoke-model）、--cli-input-json を登録しない CLI 独自実装のコマンド（s3 cp/ls/sync、logs tail、cloudformation deploy）、そして CLI がそもそも提供していないイベントストリーム操作（Bedrock の converse-stream、invoke-agent、エージェント型の Knowledge Base 検索）です。
4. 最新の AWS ドキュメント。 aws_docs_search は docs.aws.amazon.com の検索ボックスと同じバックエンドを検索し、aws_docs_read はドキュメントページを取得して、ページ分割された Markdown として返します。別の MCP サーバーをインストールしなくても、エージェントが新しいサービスを見つけたり、正確なパラメーター名を調べたりできます。
5. 1 回の往復でバッチ処理するワークフロー。 aws_script は node:vm コンテキスト内で短い JS スニペットを実行し、aws.call、aws.paginate、aws.paginateAll、aws.resource.*、aws.logsTail、aws.metricsQuery、aws.iamSimulate、aws.multiRegion、aws.assumeRole、aws.docs.{search,read} を利用できます。ほかの方法では N 回のツール呼び出しが必要になる「X を一覧表示し、それぞれについて Y を取得して、Z を返す」パイプラインに最適です。AWS の run_script（サーバー側でサンドボックス化された Python）と同じ発想です。現在、AWS のサーバーで AWS API を呼び出す汎用的な唯一の方法となっています。こちらでは、単一の操作には aws_call を使い、バッチ処理にはローカルで実行する JS ネイティブの選択肢として利用できます。

オプションの補完ツール：AWS Labs のサービス別サーバー

汎用の AWS API ツールでは対応できない作業には、このサーバーと合わせて該当する awslabs/mcp サーバーを追加してください。Bedrock のエージェント型ナレッジベース検索が最も分かりやすい例です。この処理では AgenticRetrieveStream が呼び出されますが、これは AWS CLI のコマンド一覧に含まれていないイベントストリーム操作のため、aws_call を含む CLI ベースのツールでは実行できません。（通常の検索である bedrock-agent-runtime retrieve は、一般的な aws_call 操作です。）これらは uvx で実行する Python サーバーで、このサーバーとツール名が重複しないため、問題なく併用できます。

{
  "mcpServers": {
    "aws": {
      "command": "npx",
      "args": ["-y", "@yawlabs/aws-mcp@latest"]
    },
    "aws-bedrock-kb": {
      "command": "uvx",
      "args": ["awslabs.bedrock-kb-retrieval-mcp-server@latest"],
      "env": { "AWS_PROFILE": "my-profile", "AWS_REGION": "us-east-1" }
    }
  }
}

このサーバーのエージェント型ツールはマネージドナレッジベースで動作します。また、デフォルトでは mcp-multirag-kb=true タグが付いたナレッジベースのみを一覧表示します。タグと IAM 権限については、README を参照してください。古い awslabs.lambda-mcp-server は使用しないでください。すべてのリリースが PyPI で取り下げられており、Lambda の呼び出しは aws_lambda_invoke としてこのサーバーに組み込まれています。

こちらと他の AWS MCP の使い分け

必要なこと	最適な選択肢
Node/npm のみでインストールし、ローカルの aws CLI とプロファイルを使って実行する（uv もプロキシも不要）	@yawlabs/aws-mcp
ローカルに何もインストールしない（リモートサーバー、ブラウザーでサインイン）	AWS MCP Server（OAuth）
Windows での SSO 再ログイン／ブラウザーの引き継ぎ不具合を、マシン上のすべてのツールで修正する	@yawlabs/aws-mcp（aws_login_start のデバイスコードフロー）
ツール呼び出しごとに AWS 操作を 1 つ実行する。承認プロンプトにはスクリプトではなく service、operation、params が表示される	@yawlabs/aws-mcp（aws_call）
1,300 種類を超えるリソースタイプに対する汎用 CRUD	@yawlabs/aws-mcp（aws_resource_*）
更新を適用する前にドライランする	@yawlabs/aws-mcp（aws_resource_diff）
1 回の呼び出しで複数リージョンに展開する	@yawlabs/aws-mcp（aws_multi_region）
1 回の呼び出しで複数のアカウントに同じ操作を実行する	@yawlabs/aws-mcp（aws_multi_account）
N 個のツール呼び出しを 1 回のラウンドトリップにまとめる（JS）	@yawlabs/aws-mcp（aws_script）
操作を試す前に IAM 権限を確認する	@yawlabs/aws-mcp（aws_iam_simulate）
1 つのセッションで複数アカウント／複数ロールを使用する	どちらも可 — このサーバーは呼び出しごとに設定済みの任意の profile を受け付け、STS のロールチェーン用に aws_assume_role を追加します。一方、AWS のサーバーは SigV4 のみを使い、プロキシの起動時に宣言されたプロファイルから呼び出しごとに 1 つを使用します（OAuth セッションでは 1 つのロールを使用します）
サーバー側でサンドボックス化された Python スクリプトを実行する	AWS MCP Server（run_script）
ホスト型エンドポイントを通じて、最新数日分の API カバレッジを利用する	AWS MCP Server（run_script）
AWS チームが厳選したベストプラクティスのスキルを利用する	AWS MCP Server（retrieve_skill）
Lambda のガイド付きトラブルシューティング（診断、最近の変更、トレースの概要）	AWS MCP Server（サーバーレス機能）
CLI ベースのツールでは対応できない操作向けの、型付きサービス別ヘルパー（Bedrock のエージェント型 KB 検索など）	awslabs/mcp（サービス別サーバー）

@yawlabs/aws-mcp と AWS の公式サーバーは、どちらか一方を選んでください。トレードオフを考慮して選択してください。awslabs/mcp のサービス別サーバーは、どちらを選んでも問題なく併用できます。

このサーバーが AWS の公式サーバーから取り入れたもの

功績は正当に認めましょう。ここにある 2 つの機能は、AWS 公式 MCP Server を参考にして設計されています。

• aws_script は、公式サーバーの run_script に相当します。「X を一覧表示し、それぞれについて Y を取得し、Z を返す」というパイプラインを 1 回の往復にまとめるスクリプト実行ツールです。公式サーバーでは Python を使い、サーバー側でサンドボックス化されています。また、現在はそのサーバーにおける唯一の汎用 API 経路です。こちらは JS ネイティブで、このサーバー自身のプロセス内で実行されます。詳しくはツール一覧の信頼性に関する注記をご覧ください。また、aws_call に代わるものではなく、併用できます。
• aws_docs_search / aws_docs_read は、どちらのサーバーを選んでも別途ドキュメント MCP を用意する必要がないように追加されました。公式サーバーの search_documentation / read_documentation と同じく、ライブ検索とページの読み取りに対応していますが、トピックのルーティングやスキルの結果には対応していません。

それ以外の SSO デバイスコードによる再ログイン、dry-run 差分付きの CCAPI CRUD、複数リージョンへのファンアウト、IAM の事前チェックは、このサーバー独自の機能です。

ツール

ツール	機能
aws_whoami	現在の ID（アカウント、ARN）と SSO トークンの有効期限までのカウントダウンを表示します。最初に呼び出してください。
aws_login_start	aws sso login --no-browser --use-device-code を開始し、確認用 URL と短いコード、および sessionId を返します。（2.22.0 より古い AWS CLI では、デバイス認可がすでにデフォルトのため、--use-device-code は省略されます。）
aws_login_complete	SSO サブプロセスが終了するまで待機します（ブラウザーで認証します）。新しい ID を返します。
aws_refresh_if_expiring_soon	キャッシュ済みの SSO トークンを確認し、有効期限までの残りが thresholdMinutes 未満（デフォルトは 10 分）なら自動的に更新を開始します。「期限が近いか確認し、近ければ再ログインする」処理を 1 回のラウンドトリップで行います。
aws_session_set	この MCP セッションの残りの期間に使用するデフォルトのプロファイルやリージョンを設定します。「prod に切り替える」「us-west-2 を使う」といった指定ができます。
aws_session_get	現在のセッションのデフォルト設定と、各値の取得元（session／env／default）を表示します。
aws_session_clear	セッションのプロファイル／リージョンの上書きを削除し、環境変数やデフォルト設定が再び使われるようにします。引数なしで両方を削除します。
aws_list_profiles	~/.aws/config に設定されたプロファイルの名前、リージョン、SSO メタデータを一覧表示します。プロファイルの切り替え前や、見覚えのないプロファイル名を含む SSO エラーが発生した場合に使用します。
aws_assume_role	現在の ID で STS AssumeRole を呼び出し、一時的な認証情報を新しいプロファイル（mcp-<sessionName>）として ~/.aws/credentials に保存します。クロスアカウントアクセスに使用します。シークレットとセッショントークンはディスク上に保存され、モデルには返されません。SAML や credential_process のコールドスタートが遅い場合に指定できる timeoutMs（デフォルトは 120 秒）もあります。
aws_call	任意の AWS API オペレーションを実行します。service: 's3api', operation: 'list-buckets'、任意で params（PascalCase の JSON）、任意で query（JMESPath）を指定します。解析済みの JSON を返します。手書きの CLI コマンド（s3 cp/ls/sync、logs tail）や、応答をファイルにストリーミングするオペレーション（s3api get-object、bedrock-runtime invoke-model、bedrock-agentcore invoke-agent-runtime、lambda invoke）は --cli-input-json を受け付けないため、aws_call では実行できません。エラーにはその旨と代替手段（aws_lambda_invoke、aws_logs_tail、bedrock-runtime converse、またはシェル）が示されます。待機処理は operation: 'wait <name>' として実行できます。Blob 型のパラメーターには base64 を指定します。
aws_paginate	ページ分割された list／describe オペレーションの 1 ページを取得します。query にも対応しています。nextToken／hasMore を返すので、続行するにはトークンを指定して再度呼び出します。
aws_logs_tail	1 つのロググループから最新の CloudWatch Logs イベントを取得します（aws logs filter-log-events による FilterLogEvents）。since、filterPattern、ストリーム名のフィルターを指定でき、{timestamp, logStreamName, message} オブジェクトを古い順に返します。maxEvents（デフォルトは 500、最大 10000）で上限を設定します。イベント数が多い期間では最新のイベントが保持され、truncated: true が報告されます。AWS CLI 2.35.8 以降では読み取り自体が maxEvents 件で停止するため、切り詰められた場合の totalEvents は null になります。それ以前の CLI では期間全体をスキャンし、正確な件数を報告します。呼び出し先リージョンのロググループ ARN を logGroupIdentifier として指定できます。これにより、クロスアカウント監視アカウントからソースアカウントの ARN を使用できます（AWS CLI 2.9.15 以降が必要です）。
aws_logs_query	CloudWatch Logs Insights クエリを最初から最後まで実行します。StartQuery を実行し、GetQueryResults を終端ステータスになるまでポーリングして行を返すため、開始、ポーリング、ステータス解釈を個別に行う代わりに、1 回の呼び出しで完了します。logGroupNames（1～50 個、名前のみ、または ARN）、queryString（Logs Insights QL、または queryLanguage による PPL）、および aws_metrics_query と同じ形式の startTime／endTime を指定します。期間の上限は 90 日で、limit のデフォルトは 1000 です。行は API の [{field, value}] ペアから平坦化され、プレーンなオブジェクトとして返されます。また、statistics（recordsMatched／recordsScanned／bytesScanned）も返します。課金対象は圧縮前のスキャンバイト数なので、期間を広げる前に絞り込んでください。タイムアウトまたはクライアントによるキャンセル時もクエリは停止されず、queryId が返され、結果は 7 日間取得できます。
aws_metrics_query	GetMetricData（最新の複数メトリクス／式対応 API）を使って CloudWatch メトリクスをクエリします。queries: [{id, namespace, metricName, dimensions?, statistic?, period?}] または式ベースのクエリを渡します。startTime／endTime は ISO 8601 または相対形式（'15m'、'1h'、'1d'）を受け付けます。期間は時間範囲に応じて自動選択されます。{series: [{id, label?, timestamps, values, period?, statusCode?}], periodSeconds, profile, region, nextToken, hasMore, messages?} を返します（完全なエンベロープは「安定性」を参照してください）。
aws_resource_get	typeName と identifier（例：AWS::Lambda::Function と関数名）を使い、Cloud Control API 経由で AWS リソースを読み取ります。解析済みの Properties を返します。
aws_resource_list	CCAPI 経由で指定した種類のリソースをページ分割して一覧表示します。各項目の {identifier, properties} と、nextToken／hasMore を返します。
aws_resource_create	CCAPI 経由で AWS リソースを作成します。非同期で、トップレベルに requestToken と operationStatus を返します。awaitCompletion: true を指定すると、サーバーが終端状態までポーリングし、1 回の呼び出しで完了します。
aws_resource_update	RFC 6902 JSON Patch を使い、CCAPI 経由で AWS リソースを更新します。非同期処理と awaitCompletion の形式は作成時と同じです。
aws_resource_delete	CCAPI 経由で AWS リソースを削除します。非同期処理と awaitCompletion の形式は作成時と同じです。破壊的な操作のため、最初に identifier を確認してください。
aws_resource_status	requestToken を使って非同期の CCAPI リクエストの状態をポーリングします。現在の状態を返し、operationStatus、identifier、errorCode、statusMessage をフラット化してトップレベルに配置します（PENDING／IN_PROGRESS／SUCCESS／FAILED／CANCEL_*）。
aws_resource_diff	CCAPI 更新をドライランします。現在の状態を取得し、メモリ上で JSON Patch をシミュレートして {before, after, changes[]} を返します。AWS への変更リクエストは送信されません。RFC 6902 の add／remove／replace サブセットに対応しています。add は、CCAPI の実際の更新時の動作に合わせて、存在しないオブジェクトの親を自動作成します（そのため、/Environment/Variables がまだ存在しない場合でも、/Environment/Variables/NEW_KEY のようなパッチが機能します）。changes[i].after は最終的なパッチ適用後の状態ではなく、操作 i によって生じた状態を示すため、同じパスへの連続した操作を正しく追跡できます。パッチが意図どおりの結果になるか確認する場合は、aws_resource_update の前に呼び出してください。
aws_multi_region	同じ AWS オペレーションを N 個のリージョンで並列実行します。aws_call と同じ形式ですが、regions: string[] を受け取ります。{region, ok, data?, error?}[] と okCount／errorCount を返します。一部の失敗は想定内です（サービスがすべてのリージョンで提供されているとは限らず、権限がリージョン単位で設定されている場合もあります）。1 回の呼び出しにつき最大 64 リージョンまで指定でき、同時実行数は最大 32 です。
aws_multi_account	各アカウントで roleName を引き受け、同じ AWS オペレーションを N 個のアカウントで並列実行します。呼び出し中、すべてのアカウントの認証情報はメモリ内に保持され、その呼び出しの 1 つのプロセス起動に渡されます。aws_assume_role を繰り返す場合とは異なり、~/.aws/credentials には何も書き込まれません。繰り返し実行するとアカウントごとにセクションを書き込むか、同じセクションを何度も上書きし、途中で処理が停止すると有効なキーがディスクに残ってしまうことがあります。aws_multi_region と同じエンベロープで、region の代わりに accountId を使用します。5 MB の合計上限と、上限適用前に計算される okCount／errorCount も同じです。ロールがすべてのアカウントに存在するとは限らないため、一部の失敗は想定内です。
aws_script	他のツールを連携させる短い JS スニペットを実行し、結果をまとめて返します。サンドボックスでは aws.call、aws.paginate、aws.paginateAll、aws.resource.{get,list,create,update,delete,status}、aws.logsTail、aws.metricsQuery、aws.iamSimulate、aws.multiRegion、aws.assumeRole、aws.docs.{search,read} に加え、標準的な JS 組み込み機能（JSON、Math、Date、Promise など）と console を利用できます。require／import／process／fs／fetch／タイマーはコンテキストにバインドされていません。**これはセキュリティ境界ではありません。**スクリプトはこのサーバー自身のプロセスで実行され、ホストのグローバル変数にも内部からアクセスできるため、aws_script は他のツールより厳しい制限がありません。他のツールは AWS と IAM ポリシーで制限されますが、このツールにはその制限がありません。このマシンで自分が実行してもよいスクリプトのテキストだけを渡してください。ログ行、リソースタグ、その他の AWS 応答に含まれていたテキストは決して渡さないでください。通常なら N 回のラウンドトリップが必要となる「X を一覧表示し、それぞれについて Y を取得し、Z を返す」パイプラインに最適です。結果を返すには return <value> を使います。
aws_iam_simulate	プリンシパルの IAM 権限をシミュレートします。プリンシパル X がリソース Z に対してアクション Y を実行できるかを確認します。iam simulate-principal-policy をラップしています。（アクション、リソース）のペアごとに 1 つの項目を返します。resources を省略すると、リソースが * の各アクションについて 1 つずつ返します。各項目には decision（allowed／explicitDeny／implicitDeny／unknown）、matchedStatementIds（判定を行った IAM ステートメント）、missingContextValues（ポリシーが必要としていたが指定されていないコンテキストキー）、および AWS がアクションごとに報告する permissionsBoundaryDecision と organizationsDecision が含まれます。SCP による拒否では該当するステートメント名は示されません。また、SCP が参照するキーは不足している値として報告されません。そのような場合は contextEntries に aws:RequestedRegion などを渡してください。「allowed」は必要条件ですが、十分条件ではありません。RCP、対象リソース自身のポリシー、セッションポリシー、VPC エンドポイントポリシーは評価されません。aws_whoami に表示される STS セッション ARN ではなく、IAM ロール ARN を渡してください。403 を避けるため、リスクのある操作の前に使用します。aws_call の失敗後に表示される Suggestion と組み合わせてください。呼び出し元に iam:SimulatePrincipalPolicy が必要です。
aws_lambda_invoke	Lambda 関数を同期的に呼び出し、応答ペイロードと実行ログの末尾をデコードして返します。aws_call では構造上 実行できません。aws lambda invoke は必須の位置引数として応答本文の出力先ファイルを受け取り、--cli-input-json を拒否するため、2 つ目の（Python の）MCP サーバーなしで機能する Lambda 用の手段はこれだけです。デコード済みの logTail によって、「呼び出し、ロググループを探し、末尾を取得し、対象の期間にログが含まれていることを期待する」という一連の処理を 1 回の呼び出しにまとめられます。空でない functionError は、関数の HANDLER が例外をスローしたことを示します。呼び出し自体は成功しているため ok は true で、スローされたエラーは payload に含まれます。CLI の自動再試行はこのツールでは無効になっているため、呼び出しは最大 1 回だけ送信されます。再試行すると関数が再実行されるためです。関数の完了を待つ時間は timeoutMs で指定します（デフォルトは 60 秒、最大 900000）。スロットリングされた呼び出しは実行されていないため安全に再試行できます。タイムアウト後のエラーには、呼び出しが送信されたかどうかが示されます。
aws_docs_search	AWS のドキュメントをリアルタイムで検索します（docs.aws.amazon.com の検索ボックスのバックエンドを使用）。ランク付けされた {title, url, summary, excerpt} を返します。各結果にはローカルで計算された lexicalMatch も含まれ、応答には queryTerms／termsMatchedNowhere／bestLexicalOverlap／lowRelevance が含まれます。バックエンドは常に曖昧検索の結果を 1 ページ分返し、「適切な一致なし」とは決して報告しないため、クエリに一致するものがなかったことを示す手掛かりはこれらだけです。モデルが知らない可能性のあるサービス／API／概念（新しいサービス、最近変更された API、正確なパラメーター名など）に関する適切なドキュメントページを見つけるために使用します。
aws_docs_read	https://docs.aws.amazon.com/...html ページを取得し、Markdown として返します。ナビゲーション、Cookie バナー、フィードバック用の要素は除去されます。長いページは startIndex と maxLength を使って分割取得できます。応答には hasMore と nextStartIndex が含まれます。通常は aws_docs_search から取得した URL を指定します。

インストール

MCP クライアントの設定（例：.mcp.json）に追加します。

{
  "mcpServers": {
    "aws": {
      "command": "npx",
      "args": ["-y", "@yawlabs/aws-mcp@latest"]
    }
  }
}

キーは aws にしてください（aws-mcp 以外なら何でもかまいません）。AWS の aws configure agent-toolkit ウィザードは、ホスト型サーバーを aws-mcp という名前で登録します。また、既存の aws-mcp エントリがあると、実行内容を確認せずに設定済みとして報告します。

-y フラグを指定すると、セッションを読み込むたびに自動更新されます。MCP クライアントがサーバーを起動するたびに、npx がレジストリで最新の @yawlabs/aws-mcp を確認し、より新しいバージョンがあればダウンロードします。新しいキャッシュでの初回起動では約100～500ミリ秒かかります。それ以降の起動では npm のキャッシュが使われるため（メタデータの一般的な鮮度保持期間：5分）、追加時間は約50ミリ秒以下です。サーバーの起動後は、ツール呼び出しに自動更新によるオーバーヘッドはありません。確認が実行されるのは起動時（または再起動時）のみです。別途インストールする必要はなく、初回インストールと継続的な更新の両方を -y で処理できます。

特定のバージョンに固定したい場合（自動更新はありませんが、起動時のオーバーヘッドはゼロです）は、グローバルにインストールして、設定からインストール済みのバイナリを指定します。

npm install -g @yawlabs/aws-mcp

{
  "mcpServers": {
    "aws": {
      "command": "aws-mcp"
    }
  }
}

新しいバージョンが必要になったときは、npm install -g @yawlabs/aws-mcp@latest を手動で実行してください。

セッション例

アシスタントにステージングバケットの確認を頼みましたが、SSO トークンの有効期限が切れていた場合の、アシスタントの動作と表示内容を紹介します。

You:    "How many objects are in the staging-artifacts bucket right now?"

Claude: (calls aws_whoami) -> SSO session expired for profile 'staging'.
        (calls aws_login_start with profile='staging')
        "Your SSO token expired. Open
         https://device.sso.us-east-1.amazonaws.com/
         and enter code: ABCD-EFGH
         I'll wait."

You:    *click, authenticate in your browser*

Claude: (calls aws_login_complete with the sessionId)
        (calls aws_call with service='s3api', operation='list-objects-v2',
                         params={ Bucket: 'staging-artifacts' },
                         query='KeyCount')
        "There are 4,182 objects in staging-artifacts."

SSO のフローはワンクリックで完了しました。「ブラウザーが開かなかったので、ターミナルで実行します」というコンテキスト切り替えは必要ありません。

より大きなリストの場合――このサーバーの5 MBの上限よりはるかに小さい、MCP ホストの出力上限を超えるような場合――アシスタントは aws_paginate を使います。

(calls aws_paginate with service='ec2', operation='describe-instances',
                        maxItems=50,
                        query='Reservations[].Instances[].{Id:InstanceId,State:State.Name}')
-> returns one page + a nextToken; Claude calls again until hasMore=false

query（JMESPath）を指定すると、サーバー側でレスポンスを絞り込めます。必要なフィールドが2つだけの場合、一般的な describe-instances の結果はメガバイト単位からキロバイト単位に縮小します。

「このリソースを作成して、準備ができたら知らせて」という場合は、aws_resource_create に awaitCompletion: true を指定すると、通常の作成後にポーリングする処理を1回のツール呼び出しにまとめられます。

(calls aws_resource_create with
   typeName='AWS::SSM::Parameter',
   desiredState={Name: '/my/param', Type: 'String', Value: 'hello'},
   awaitCompletion: true)
-> server polls get-resource-request-status until SUCCESS / FAILED / CANCEL_COMPLETE
   and returns the terminal ProgressEvent in one call

aws_resource_update と aws_resource_delete も同様です。デフォルトの開始後にポーリングする動作を使う場合は、awaitCompletion を省略するか、false に設定します。時間のかかる更新を開始し、後で状況を確認したい場合に便利です。

「適用する前にパッチをプレビューして」という場合は、次のようにします。

(calls aws_resource_diff with
   typeName='AWS::Lambda::Function',
   identifier='my-fn',
   patchDocument=[{op: 'replace', path: '/MemorySize', value: 1024}])
-> returns { before: {MemorySize: 256, ...}, after: {MemorySize: 1024, ...},
              changes: [{op: 'replace', path: '/MemorySize', before: 256, after: 1024}] }

AWS に変更リクエストは送信されません。エージェントは aws_resource_update を呼び出す前にパッチを確認できます。

バッチ処理のワークフローでは、aws_script を使うと N 回のツール呼び出しを1回にまとめられます。

(calls aws_script with code=`
   const listed = await aws.resource.list({ typeName: "AWS::Lambda::Function" });
   const big = [];
   for (const r of listed.resources) {
     const cfg = await aws.resource.get({
       typeName: "AWS::Lambda::Function", identifier: r.identifier });
     if (cfg.properties.MemorySize > 1024) {
       big.push({ name: cfg.properties.FunctionName, mem: cfg.properties.MemorySize });
     }
   }
   return big;
`)
-> one round-trip; the agent gets the filtered list without N intermediate tool calls

複数リージョンからの読み取りには、次のようにします。

(calls aws_multi_region with
   service='ec2', operation='describe-instances',
   regions=['us-east-1','us-west-2','eu-west-1'],
   query='Reservations[].Instances[].InstanceId')
-> {okCount: 3, errorCount: 0, results: [{region, ok, data}, ...]}

要件

• Node.js 22+（または oam.js — ランタイムを参照）
• PATH 上に AWS CLI v2 があること。AWS と通信するすべてのツール（aws_docs_*、aws_session_*、aws_list_profiles 以外）は AWS CLI を呼び出すため、インストール済みの CLI によって利用可能なサービス、操作、パラメーターが決まります。最低バージョンは指定していません：
  • 2.22.0 以降を推奨します。 このリリースで --use-device-code が追加されました。これは、このサーバーで SSO の短縮コードフローを引き続き機能させるために必要です。古い 2.x でも引き続き動作します。サーバーがバージョンを検出し、適切に対応します。
  • 2.34.3 を使用して開発・テストしています。 使用中の CLI より新しい機能は、リクエストの送信前に CLI によって拒否されます。サービスや操作が不明な場合は「invalid choice」（このエラーにはアップグレードを促すメッセージが表示されます）、新しいパラメーターの場合は Unknown parameter in input となります。AWS のインストーラーまたはインストールスクリプトでインストールした場合は aws update（CLI 2.36.0 以降）で、それ以外の場合はインストーラーまたはパッケージマネージャーでアップグレードしてください。
  • セキュリティ（2026-09 時点）： CLI 2.35.3 以降では、公開済みの AWS CLI v2 のすべてのアドバイザリ（GHSA-747p-wmpv-9c78、CVE-2026-13769、CVE-2026-18654）に対応しています。影響を受ける経路は、このサーバーからは利用できません。該当する4つのコマンド（emr ssh/socks/put/get、codeartifact login、deploy register、iam create-virtual-mfa-device）はいずれも --cli-input-json を登録しておらず、aws_call がパラメーターを渡す方法はこれだけです。また、3つ目のアドバイザリはオプトイン機能の cli_history データベースに関するものですが、このサーバーでは有効化しません。ただし、同じ CLI インストールをマシン上のほかのすべての用途と共有しています。v2 はインストーラーとして提供されるため、依存関係スキャナーでは検出されません。新しいアドバイザリがないか、アドバイザリ一覧を確認する価値があります。
  • AWS CLI v1 はサポート対象外です。2026-07-15 にメンテナンスモードに入り、2027-07-15 にサポートが終了します。
• CLI で使用できる AWS プロファイルがあること — プロファイルの選択方法については環境を参照してください。SSO / IAM Identity Center プロファイルでは、デバイスコードによる再ログインツールも利用できます。

ランタイム

このサーバーは oam.js と Node の両方で変更なしに動作します。ランチャーは 0.18.0 より古い oam ではサーバーを起動せず、この最低バージョン以上で見つかった oam バイナリのうち最も新しいものを選択します。oam 0.18.0（aarch64-pc-windows-msvc）で検証済みです。MCP ハンドシェイクで28個のツールすべてを一覧表示すること、ローカルツールの呼び出し、後述する aws_script のサンドボックス動作を確認しています。

oam 0.18.0 が最低バージョンです。 ランチャーはこのバージョン以上で見つかった oam のうち最も新しいものを選択し、それより古いバージョンではサーバーを起動せず、該当するバージョンがない場合は Node にフォールバックします（AWS_MCP_RUNTIME=oam を指定するとエラーになります）。最低バージョンの指定には理由があります。0.9.0 より前のリリースでは、child_process.execFile の引数がシェル経由で実行され、exec の timeout が受け入れられても無視され、stdio: 'inherit' が 'pipe' として扱われていました。このサーバーは、ほぼすべてのツールで AWS CLI をシェル経由で呼び出します。

oam で実行するには、MCP クライアントの command を次のように指定します：

{
  "mcpServers": {
    "aws": {
      "command": "oam",
      "args": ["run", "/path/to/aws-mcp/dist/index.js"],
      "env": { "AWS_PROFILE": "my-sso-profile", "AWS_REGION": "us-west-2" }
    }
  }
}

お使いのハードウェアで起動時間を計測してください。 MCP クライアントはセッションごとにこのサーバーを1回コールドスタートするため、実際に発生するコストは起動時間です。以下の数値は、現在の最低バージョンである 0.18.0 よりかなり前の oam 0.8.2 で測定したもので、その後は再測定していません。そのため、現在のランキングとして解釈しないでください。initialize + tools/list のハンドシェイクが完了するまでの、ウォームアップ後10回の実行の中央値です：

ランタイム	コールドスタート
node dist/index.js	359 ms
oam run dist/index.js	650 ms
oam run src/index.ts（ビルド手順なし）	947 ms
公開されている aws-mcp コマンドは、見つかった中で最も新しい oam を優先します（環境の AWS_MCP_RUNTIME を参照してください）。oam がなければ、コストはほとんどかかりません。検出時に行うのはファイルの存在確認だけで、サブプロセスは起動せず、フォールバックでは npm がすでに起動した Node プロセス内でサーバーを実行します。ただし、oam がインストールされている場合、このコマンドは Node を起動し、見つかったすべての oam バイナリに対して --version を実行して最新のものを選んでから、ようやく oam を起動します。そのため、上記の設定でクライアントから oam を直接指定するより、常に遅くなります。AWS_MCP_RUNTIME=node を指定すると、oam を完全にスキップします。

このリポジトリで oam が優れている点は、ほかにも2つあります。どちらもオプトインであり、公開されている npm パッケージには影響しません。

• npm run check:oam -- oam check（ネイティブの TypeScript 7 である tsgo）を使って型チェックを行います。計測では、tsc --noEmit の約3.8～4.7秒に対して約1.0秒でした。同じ tsconfig.json を解決し、テストを含む同じファイルを対象とします。テストファイルに型エラーを仕込み、どちらもエラーを検出することを確認済みです。引き続き、移植性の高いデフォルトとして npx tsc --noEmit を使用できます。
• npm run build:binary:oam -- oam compile を使ってスタンドアロンバイナリをビルドします。win32-arm64 での計測値は58.60 MBで、約493 KBの埋め込みV8バイトコードを含みます。bin/<platform>-<arch>/ に出力され、リリースのステージングスクリプトがこれを使用します。このバイナリを再配布する場合、oam のランタイムが埋め込まれるため、oam の LICENSE、NOTICE、THIRD_PARTY_LICENSES.md も同梱してください。

ソースがランタイムに依存しないのは意図的です。oam: のインポートは一切なく、テストには引き続き node:test を使います。これにより、Node のフォールバックは名目上ではなく、実際に機能します。

oam で aws_script を実行する場合に知っておくべき動作の違いが1つあります。Node は node:vm コンテキストの codeGeneration: { strings: false } を尊重するため、eval と Function は例外をスローしますが、oam はこの設定を尊重しないため、これらを使えます。oam 0.18.0 に対して再計測しても違いは変わっていません。サンドボックス内では、oam で eval('1+1') は 2 を返し、Function('return 7')() は 7 を返しますが、Node ではどちらも EvalError が発生します。そのため、これは継続的な違いとして扱ってください。重要な封じ込めには影響しません。oam では Function('return this')() が返すグローバルの process と require はどちらも undefined であり、Function('return require') は例外をスローします。そのため、スクリプトは同じコードを本体に書いた場合にできること以上のことはできません。aws_script はもともとセキュリティ境界ではありません（説明を参照してください）。実際の防御となるのはシャドウ化されたグローバルのリストであり、そのフラグではありません。

なお、oam を実行すると、作業ディレクトリの oam/ にバイトコードキャッシュが書き込まれます。このディレクトリはすでに .gitignore に含まれています。

環境

変数	デフォルト	用途
AWS_PROFILE / AWS_DEFAULT_PROFILE	default	ツール呼び出しで profile が省略された場合に使用するプロファイルです。AWS_DEFAULT_PROFILE は旧式の表記です。両方が設定されている場合は、AWS CLI v2 と同様に AWS_PROFILE が優先されます（単体の botocore と boto3 は AWS_DEFAULT_PROFILE を先に確認します）。空の値は未設定として扱われます。
AWS_REGION / AWS_DEFAULT_REGION	us-east-1	ツール呼び出しで region が省略された場合に使用するリージョンです。両方が設定されている場合は AWS_REGION が優先されます。
AWS_SHARED_CREDENTIALS_FILE	~/.aws/credentials	aws_assume_role が作成したプロファイルを書き込む場所です。botocore と同様に ~ の展開を行って反映されるため、CLI が後で読み込むファイルと同じ場所に書き込まれます。
AWS_MCP_AWS_CLI	未設定	PATH 上で見つかったものの代わりに実行する aws 実行ファイルの絶対パスです。GUI から起動した MCP ホストは、多くの場合シェルの PATH をまったく継承しません。また、AWS が推奨するインストーラーは現在、macOS と Linux でデフォルトの配置先を ~/.local/bin にしており、このようなホストからはほとんど見えません。command -v aws（macOS/Linux）または where.exe aws（Windows）でパスを確認してください。Windows の Git Bash では command -v aws ではなく where.exe aws を使用してください。前者は POSIX 形式のパス（/c/Program Files/...）を出力しますが、この変数はネイティブな絶対パスを要求するため、その形式を受け付けません。この設定はすべての呼び出しと aws sso login に適用されます。絶対パスでなければならず、Windows では aws.exe を指定する必要があります。.cmd または .bat のシムはシェルなしでは起動できません。使用できない値が指定されると、設定と異なる CLI を黙って実行するのではなく、この変数名を含むメッセージを出して、すべての呼び出しが失敗します。未設定の場合、サーバーは PATH 上の絶対パスのディレクトリをたどります。作業ディレクトリにある aws は実行しません。

公開されている aws-mcp コマンドが実行するランチャー（npx @yawlabs/aws-mcp が起動する bin/aws-mcp.mjs）は、さらに2つの変数を読み込みます。これらはランタイムを選択するもので、AWS に関する設定ではありません。クライアントから dist/index.js を直接指定すると、どちらも適用されません。oam 上での実行による変更については、ランタイムを参照してください。

変数	デフォルト	用途
AWS_MCP_RUNTIME	auto	auto：ランチャーがすでに実行されている oam が 0.18.0 以降であれば、その上でサービスを提供します。そうでない場合は、見つかった最新の oam バイナリ（0.18.0 以降、OAM_BIN を参照）を使用し、それもなければ Node で実行します。0.18.0 より古い oam ホストがサーバー自体を提供することはありません。最も新しい使用可能な oam に処理を引き継ぐか、PATH 上の Node に引き継ぐか、どちらもなければエラーで終了します。使用できない OAM_BIN は必ず標準エラー出力に表示されます。それ以外の、使用可能な oam が見つからずに候補から除外された oam バイナリは、その場合にのみ名前が表示されます。oam：同じ動作ですが、Node にフォールバックせずエラーで終了します。node：常に Node を使用します。npx の下では同一プロセス内で実行され、クライアントが oam run でコマンドを起動した場合は PATH 上の Node に処理を引き継ぎます。大文字と小文字は区別されません。それ以外の値は auto と同じように動作します。
OAM_BIN	未設定	検出より優先して使用する oam バイナリのパスです。0.18.0 以降である必要があります。存在しない場合、古い場合、または実行できない場合、ランチャーはその旨を標準エラー出力に表示して検出を続行します。検出では、OAM_INSTALL_DIR が設定されていればそのディレクトリ（oam インストーラー独自のインストール先）を確認し、次にインストール済みの場所（Windows では %LOCALAPPDATA%\oam\bin、続いて ~/.oam/bin、それ以外では ~/.oam/bin）、さらに PATH を確認します。見つかったすべての oam にバージョンを問い合わせ、最も新しいものを使用します。同じバージョンの場合はインストール済みのものが優先されます。Windows では oam.exe のみが対象です。oam.cmd / oam.bat のシムは実行されず、使用可能な oam が見つからない場合は標準エラー出力に名前が表示されます。AWS_MCP_RUNTIME=node の場合、およびすでに oam 0.18.0 以降で実行されている場合は無視されます。
サーバーがすべての aws 呼び出しで設定する環境変数です。 各 aws 子プロセスには次の環境変数が設定され、シェルや ~/.aws/config の設定より優先されます。いずれも、このサーバーが解析する出力に影響するためです。AWS_CLI_ERROR_FORMAT=enhanced（CLI 2.34.0 の json／yaml／text／table エラー形式では、errorKind の分類で読み取る An error occurred (Code) というテキストが取り除かれます）、AWS_CLI_AUTO_PROMPT=off（自動プロンプトはコンソールを必要とするため、MCP ホストからの呼び出しでは aws sso login を含め、毎回失敗します）、AWS_CLI_OUTPUT_ENCODING=utf-8 と PYTHONUTF8=1（Windows では、これらがないと CLI は ANSI コードページで出力するため、そのコードページに含まれない文字があると失敗します）。さらに Windows では、NoDefaultCurrentDirectoryInExePath=1 も設定されます（session-manager-plugin など、CLI 独自のヘルパーが作業ディレクトリから実行されないようにします）。これらはフラグではなく環境変数なので、いずれかを認識しない古い 2.x CLI は、その変数を無視するだけです。副作用が 1 つありますが、Windows のみに該当します。2.25.0 より古い CLI では、PYTHONUTF8=1 によって CLI が ~/.aws/config と ~/.aws/credentials も UTF-8 として読み込むため、従来の Windows コードページで保存された非 ASCII 文字があると解析に失敗します。その場合は、ファイルを UTF-8 で保存し直すか、CLI を更新してください。macOS と Linux では、ANSI コードページから切り替える必要がないため、この設定によるコストはありません。linux/arm64 の aws-cli 2.36.49 で測定したところ、~/.aws/config に cp1252 のバイトが含まれている場合、PYTHONUTF8 が未設定、=0、=1 のいずれでも、また LC_ALL=C と LC_ALL=POSIX のどちらでも同じように解析に失敗しました。一方、同じ文字を UTF-8 でエンコードすると、いずれの条件でも解析できます。params を含む呼び出しには --cli-binary-format base64 も渡されるため、設定内容にかかわらず、blob 型のパラメーターは常に base64 になります。意図的に設定に委ねている項目は、再試行モードと最大試行回数、cli_timestamp_format（CLI では設定ファイルでのみ指定でき、wire では ISO 形式の文字列ではなくエポック秒が返されます）、cli_history、エンドポイント、プロキシ、CA の設定です。

SAML（Okta／Azure AD／ADFS）またはカスタムの credential_process で認証する場合は、そのプロファイルを AWS_PROFILE に設定してください。

すべての呼び出しでは、まずプロファイル名が次の順序で解決されます――ツールの profile 引数 -> aws_session_set で設定されたセッションプロファイル -> $AWS_PROFILE -> $AWS_DEFAULT_PROFILE -> リテラルの default。その後、--profile <name> として CLI に渡されます。「プロファイルなし」のモードはありません。ただし例外として、aws_multi_account では、解決されたプロファイルは sts:AssumeRole 呼び出しにのみ使われます。アカウントごとの操作はそれぞれ、そのアカウントの引き受けたロールの認証情報を使い、--profile フラグなしで実行されます。選択されたプロファイル内では、CLI 独自の認証情報チェーンが通常どおり解決を行います。対象は、credential_process、SSO セッション（sso_session ブロックとインラインの sso_start_url の両方）、source_profile／role_arn によるロールの連鎖、~/.aws/credentials に保存された静的キー、コンテナ認証情報、IMDS です。

例外 -- 環境変数に設定された静的キーは使われません。 プロファイルが常に明示的に渡されるため、botocore は認証情報チェーンから環境変数プロバイダーを除外します。そのため、シェルでエクスポートされた AWS_ACCESS_KEY_ID／AWS_SECRET_ACCESS_KEY／AWS_SESSION_TOKEN は参照されません。（コンテナ認証情報と IMDS には影響しません。これらはチェーン内で後に評価され、プロファイルの指定には左右されません。）静的キーを使うには、環境変数としてエクスポートするのではなく、~/.aws/credentials のプロファイルセクションに設定し、そのプロファイルを AWS_PROFILE に指定してください。

プロキシまたはプライベート CA の背後で使用する場合

aws_docs_search と aws_docs_read はこのプロセスから HTTPS 経由で取得するため、企業ゲートウェイによって問題が発生するのはこの 2 つのツールです。原因を AWS のバックエンドのせいにせず、原因そのものを示すようになりました。修正するには、MCP 設定に env エントリを追加します。シェルで export するのではありません。以下の 2 つの変数はプロセスの起動時に読み込まれ、MCP クライアントがサーバー自体を起動するためです。

変数	用途
NODE_EXTRA_CA_CERTS	TLS インターセプトにより、自己署名または発行者不明のエラーで取得に失敗する場合に、ゲートウェイの CA 証明書を格納した PEM ファイルのパスを指定します。
NODE_USE_SYSTEM_CA=1	ファイルを指定する代わりに、オペレーティングシステムの証明書ストアを信頼します（Node 22.19 以降）。
HTTPS_PROXY / https_proxy	経由して取得するプロキシです。Node では、NODE_USE_ENV_PROXY=1 または --use-env-proxy で明示的に有効化しない限り、無視されます（Node 22.21 以降。NODE_OPTIONS 内での指定も可能です）。有効化しない場合、リクエストは直接接続し、プロキシ経由のみのネットワークではタイムアウトします。oam 上で実行する場合は、明示的な有効化なしでこの変数が適用されます。

AWS CLI は独立したプロセスであり、独自のルールに従います。そのため、同じゲートウェイ経由の credential_process、SSO ログイン、または aws_call は、上記の Node 変数ではなく、AWS CLI 独自のプロキシ設定（HTTP_PROXY / HTTPS_PROXY および AWS_CA_BUNDLE）に従います。これらの失敗にも、それぞれ対処方法が表示されるようになりました。

呼び出しで profile が省略され、aws_session_set が呼び出されておらず、AWS_PROFILE も AWS_DEFAULT_PROFILE も空でない値に設定されておらず、さらに ~/.aws/config と ~/.aws/credentials のどちらにも default プロファイルが定義されていない場合、CLI は --profile default を ProfileNotFound で拒否します。ツールはこれを no_creds エラーとして報告します。MCP 設定で AWS_PROFILE を通常使用するプロファイルに設定してください。

SSO ログインフローの仕組み

1. Claude calls aws_login_start({ profile: "prod" })
2. Server spawns: aws sso login --no-browser --use-device-code --profile prod
   (--use-device-code keeps the CLI on the device grant; without it, 2.22.0+
    prints an authorize URL with no short code to surface)
3. Server parses the URL + code from stdout, returns them to Claude
4. Claude surfaces: "Open https://device.sso.us-east-1.amazonaws.com/ and enter ABCD-EFGH"
5. You click — browser opens in your own user session — auth in ~10 seconds
6. Claude calls aws_login_complete({ sessionId })
7. Tool returns your new identity. Back to work.

トークンは通常の aws sso login と同じ方法で ~/.aws/sso/cache/<hash>.json にキャッシュされるため、AWS CLI、SDK、およびマシン上のほかのすべてのツールで透過的に使用できます。

このサーバーをローカルで実行する必要がある理由（mcp.hosting 上ではなく）

SSO トークンは、お使いのデバイス上の ~/.aws/sso/cache/ に保存されます。リモート MCP サーバーはそのトークンを読み取れません。そのため、これはホスト型ではなく stdio サーバーです。これは AWS SSO の制約であり、mcp.hosting の制限ではありません。

安定性

1.0 以降、このパッケージはセマンティックバージョニングに従います。0.x 系は安定化前の調整段階です。破壊的変更は CHANGELOG.md に記載されますが、必ずしもメジャーバージョンの更新を条件とするわけではありません。

1.x で安定している項目（以下の内容に対する変更は、メジャーバージョンの更新が必要となる破壊的変更です）：

• ツール名 -- 上記のツール表に記載されている28個のツール名は、変更も削除もされません。

• ツールのアノテーション -- readOnlyHint、destructiveHint、idempotentHint、openWorldHint。これらは、MCP ホストに呼び出しを制御する方法を示します。黙って値を反転すると、ホストの UI が壊れてしまいます。保証の方向に注意してください。ツールができることを以前のアノテーションが過小評価していた場合、パッチリリースでアノテーションをより厳格（より慎重）にすることはあります。そのため、v2.0.1 では aws_call、aws_multi_region、aws_resource_update に destructiveHint: true を設定しました。メジャーリリース以外で緩和されることはありません。ホストがこれらを基に確認プロンプトを抑止する場合は、aws_call と aws_multi_region が、呼び出し元の IAM ID に許可されたあらゆる AWS API（削除を含む）を呼び出せるものとして扱ってください。

• 必須入力フィールド -- ツールごとの必須フィールドの構成は変更も削除もされません。新しい任意フィールドが追加されることはあります。

• ツールごとの成功エンベロープの形式 -- {ok: true, data} レスポンスの data オブジェクト、具体的には次のとおりです。

  • aws_call -> {command, commandArgv, result}
  • aws_paginate -> {command, result, nextToken, hasMore}
  • aws_multi_region -> {service, operation, regionCount, okCount, errorCount, results: [{region, ok, data?, command?, error?, errorKind?, truncated?}]}（集約レスポンスには上限があります。上限を超えたエントリーは region／ok を保持しますが、data は省略され、truncated: true が設定されます。エラーのエントリーは削除されません。また、okCount／errorCount は上限適用前に算出されるため、上限内に残った結果ではなく、呼び出しの実際の結果を常に表します。）
  • aws_multi_account -> {service, operation, roleName, accountCount, okCount, errorCount, results: [{accountId, ok, data?, command?, error?, errorKind?, truncated?}]}。5 MB の集約上限に達した場合は、さらに truncated、truncatedAccounts、maxTotalResultBytes が含まれます。region の代わりに accountId を使う以外は、フィールドごとに aws_multi_region と同じです。これには、okCount／errorCount が上限適用前に算出され、上限内に残った結果ではなく呼び出しの実際の結果を表すことも含まれます。重複するアカウント ID は統合されるため、results.length が accounts.length を下回る場合があります。accountCount を使用してください。認証情報が ~/.aws/credentials に書き込まれたり、command、error、rawBody に表示されたりすることはありません。
  • aws_whoami -> {account, userId, arn, profile, region, ssoToken: {expiresAt, minutesLeft, startUrl?} | null}（キャッシュされたトークンに startUrl が記録されていない場合、startUrl は省略されます）
  • aws_login_start -> {sessionId, profile, verificationUrl, userCode, instructions, reused?}（同じプロファイルの進行中のログインを再提示する場合は reused: true）
  • aws_login_complete -> {loggedIn, account, userId, arn, profile, region, ssoToken}（aws_whoami と同じ ssoToken の形式で、任意の startUrl も含みます）
  • aws_refresh_if_expiring_soon -> 分岐に応じて次の2種類の形式のいずれかになります。 キャッシュされたトークンの残り時間が thresholdMinutes より長い場合は {status: "ok", minutesLeft, expiresAt, profile}、更新が進行中の場合は {status: "refreshing", reason, sessionId, profile, verificationUrl, userCode, reused?, instructions} です。status で判別してください。
  • aws_assume_role -> {profile, credentialsPath, expiration, assumedRoleArn, assumedRoleId, sourceProfile, hint, warning?}（warning は、対象プロファイルがすでに存在し、その3つの認証情報キーがその場で上書きされた場合にのみ含まれます。AWS_SHARED_CREDENTIALS_FILE が設定されている場合、credentialsPath はその値に従います）
  • aws_list_profiles -> {configPath, profiles: [{name, region?, ssoStartUrl?, ssoRegion?, ssoSession?, isSso}]}
  • aws_session_get / aws_session_set / aws_session_clear -> {profile, region, profileSource, regionSource}（*Source は "session" | "env" | "default" のいずれかです）。3つとも同じ形式を返します（set／clear は変更後の状態を返します）。
  • aws_resource_get -> {command, typeName, identifier, properties, propertiesRaw?}
  • aws_resource_list -> {command, typeName, resources: [{identifier, properties, propertiesRaw?}], nextToken, hasMore}（Properties 文字列の解析に失敗したエントリーには propertiesRaw が付随し、aws_resource_get と同じ動作になります）
  • aws_resource_create / _update / _delete / _status -> {command, requestToken, operationStatus, identifier, errorCode, statusMessage, retryAfter, progressEvent} をフラットに昇格した形式です。awaitCompletion: true が指定された場合は awaited: {attempts, elapsedMs} ブロックが追加されます。awaitCompletion: true が指定されていてもポーリング対象のリクエストトークンが返されなかった場合は、代わりに awaitSkipped 文字列が含まれます。
  • aws_resource_diff -> {command, typeName, identifier, before, after, changes, changeCount}
  • aws_logs_tail -> {command, logGroupName, logGroupIdentifier, since, eventCount, totalEvents, truncated, events}。各イベントは {timestamp, logStreamName, message} です。timestamp はミリ秒を含む ISO 8601 UTC 形式で、message はイベントのテキストそのものです。メンバーのない状態で届いたイベントでは、3つの値のいずれかが null になります。そのようなイベントは削除されず保持されるため、eventCount はサービスが返した件数と一致します（実際の CloudWatch は3つすべてを返しますが、それと異なるエンドポイントではそうならない場合があります）。events は古い順で、maxEvents（デフォルトは500）を上限とし、最新のイベントを保持します。eventCount は events の件数であり、それを超えるイベントがウィンドウ内にある場合に限り truncated は true です。totalEvents はツールがウィンドウ全体を読み取った場合のイベント数で、途中で停止した場合は null です。AWS CLI 2.35.8+ では新しい順に読み取り、maxEvents を超えた時点で停止するため、その場合、切り詰められた結果の totalEvents は null になります。一方、古い CLI、または FilterLogEvents の startFromHead を無視するエンドポイントでは、ウィンドウ全体を読み取り、正確な件数を返します。logGroupName は常にグループ名のみです。入力が ARN の場合、logGroupIdentifier は FilterLogEvents に送信される ARN（末尾の :* を除去したもの）で、それ以外の場合は null です。
  • aws_logs_query -> {command, startCommand, profile, region, queryId, status, queryLanguage, logGroupNames, startTime, endTime, fields, rows, rowCount, statistics, truncated, polled: {attempts, elapsedMs}}。ok: true の場合、status は常に "Complete" です。それ以外のすべての終端状態（Failed、Cancelled、Timeout、未認識の状態、状態がない場合）は ok: false を返します。また、maxWaitMs のタイムアウトとクライアントによるキャンセルも ok: false となり、どちらもエラー文字列に queryId を含みます（エラーエンベロープには data がないためです）。command は最後の get-query-results 呼び出し、startCommand は start-query 呼び出しです（その --cli-input-json ペイロードは秘匿されるため、クエリテキストは返されません）。rows は API の [{field, value}] ペアを単純なオブジェクトに平坦化したもので、文字列以外の値は null になります。fields はフィールド名を初めて現れた順に集めたものです。logGroupNames は実際にクエリされた名前のみの解決済みロググループ名です（ARN を入力した場合は、抽出した名前が返されます）。レスポンスに queryLanguage や statistics がない場合、それらは null になります。rowCount が実効的な limit に達した場合、truncated は true です。このツールが AWS 側でクエリを停止することは、どの経路でもありません。
  • aws_metrics_query -> {command, profile, region, startTime, endTime, periodSeconds, series: [{id, label?, timestamps, values, period?, statusCode?}], nextToken, hasMore, messages?: [{code?, value?}]}（messages は空の場合は省略されます。系列ごとの label／period／statusCode は、CloudWatch が返す場合、またはクエリで期間が指定／継承される場合に含まれます。CloudWatch がレスポンスを切り詰めない限り、nextToken は null で hasMore は false です）
  • aws_iam_simulate -> {command, principalArn, summary: {allowed, denied, unknown, total}, results, marker, hasMore}（results には、IAM のリソースごとの ResourceSpecificResults から読み取った、（アクション、リソース）ペアごとのエントリーが1つずつ含まれます。resources を指定せずに呼び出すと、アクションごとに resource: "*" のエントリーが1つ含まれます。アクションをリソースごとに分解しない AWS の場合は、AWS 自身の EvalResourceName（* またはそのアクションの ARN テンプレート）を持つエントリーが1つ含まれます。summary はエントリー数を集計します。リソースごとの値が AWS から返されない場合、organizationsDecision と permissionsBoundaryDecision は AWS のアクションレベルの値にフォールバックします。ただし、allowed のエントリーは常に "allowed" を使用します。unknown は、判定が欠落または未認識のエントリー数です。不正なレスポンスが denied に暗黙にまとめられることはありません。CLI が IAM のページネーションを自ら処理するため、最初の呼び出しは完了済みで、hasMore: false、marker: null になります。2つの値がカーソルを持つのは marker から再開した呼び出しの場合のみで、その場合、summary はそのページのみを表します。）
  • aws_lambda_invoke -> {command, statusCode, functionError, executedVersion, payload, logTail}。レスポンス本文が切り詰められた場合にのみ payloadTruncated: true が追加されます（それ以外では省略され、サイズ報告ではなく例外フラグとして機能します）。logTail は、関数の LogResult をすでに base64 デコードしたものです。空でない functionError があっても、ok: true です。呼び出し自体は成功しており、関数のハンドラーが例外を発生させたことを意味します。発生したエラーは payload に含まれます。呼び出しの失敗（関数名が不正、権限がない、スロットリング、タイムアウト）は ok: false となります。呼び出しが複数回送信されることはありません。errorKind: "timeout" は時間内に応答がなかったことを意味し、そのメッセージには呼び出しが送信されたかどうかが記載されます（送信済みの場合、関数は実行された可能性があり、実行中の可能性もあります）。
  • aws_script -> {result, logs, truncatedLogs, durationMs}。result は、スクリプトが return した値（undefined を含む、JSON にシリアライズ可能な任意の値）です。
  • aws_docs_search -> {query, count, results: [{title, url, summary?, excerpt?, lexicalMatch}], queryTerms, termsMatchedNowhere?, bestLexicalOverlap, lowRelevance, relevanceNote?}（summary／excerpt は、上流の検索バックエンドが返した場合のみ含まれます。2.1.0 以降に提供されている関連度フィールドは、このサーバーがローカルで計算します。クエリの語句と結果のタイトル／要約／抜粋との文字どおりの単語の重複であり、バックエンドのスコアでも意味的な順位付けでもありません。結果には注釈が付くだけで、並べ替えは行われません。結果ごとの lexicalMatch は {overlap, matchedTerms, unmatchedTerms} です。スコアリング可能な語句がないクエリでは null となり、その場合 bestLexicalOverlap も null で、termsMatchedNowhere は省略されます。最良の結果がクエリ語句の半分以下にしか一致しない場合、どの結果にも現れない語句がある場合、またはバックエンドが何も返さなかった場合、lowRelevance は true です。relevanceNote は、lowRelevance の判定、またはスコアリング可能な語句がない場合についての文章による説明です。説明する内容がなければ省略されます。）
  • aws_docs_read -> {url, cached, content, startIndex, endIndex, totalLength, hasMore, nextStartIndex}

• エラーエンベロープ -- {ok: false, error: string, rawBody?: string, errorKind?: string, suggestion?: string}。error 文字列は人が読める形式で、その文言は可能な範囲での提供です（下記参照）。安定した機械可読の情報は errorKind です（下記の列挙型を参照）。suggestion には、認識された AWS エラーコードに対する1行の対処法が含まれます。これは error の末尾にも埋め込まれるため、追加情報ではなく、プログラムから呼び出す場合の便宜を図るものです。ワイヤー上でエラー結果は単一のテキストブロックであり、errorKind は独立した最初の行に記載されます。errorKind: <kind> の後に改行、続いて Error: <message>、さらに空行の後、メッセージ内でまだ引用されていない場合は rawBody が続きます。分類されない失敗ではこの行が省略され、従来どおり Error: から始まります。

• errorKind の列挙型 -- "sso_expired" | "expired_creds" | "no_creds" | "invalid_creds" | "bad_input" | "spawn_failure" | "timeout" | "output_too_large" | "malformed_json" | "nonzero_exit" | "unexpected" | "cancelled"。これは異なるルールが適用される、2つの別個の箇所に現れます。 トップレベルのエラーエンベロープでは、aws CLI 呼び出しをラップするすべてのツール、つまり aws_call、aws_paginate、aws_logs_tail、aws_logs_query、aws_metrics_query、aws_iam_simulate、aws_lambda_invoke、aws_assume_role、aws_whoami、aws_login_complete、aws_resource_* ファミリーが対象です。失敗が CLI に到達しなかった場合、ここに errorKind は存在せず、デフォルト値も設定されません。該当するのは、ツール独自の入力検証、aws_docs_* の HTTP エラー、クライアントによってキャンセルされたポーリングです。errorKind がない場合は nonzero_exit ではなく、「未分類」として扱ってください。

  ファンアウトツールの results 配列の各エントリーでは、aws_multi_region と aws_multi_account が対象です。失敗したエントリーには、CLI に到達しなかった場合も含め、エントリーごとの errorKind が常に存在します。両ツールは、自ら拒否したエントリー（不正なリージョン名、12 桁ではないアカウント ID）を bad_input として分類し、ワーカーが例外をスローしたエントリーを unexpected として分類します。unexpected はファンアウト専用であり、トップレベルのエンベロープには現れません。同様に、cancelled もトップレベルには現れません。これは、ワーカーが処理を開始する前にクライアントがリクエストをキャンセルしたため、一度も試行されなかったエントリーを示します。cancelled のエントリーについて AWS には何も送信されていません。すでに実行済みのエントリーは実際の結果を保持し、配列にはリクエストされた全項目が引き続き含まれるため、キャンセルされた一括処理を、より小規模で成功した処理と okCount／errorCount が誤認することはありません。

  新しいバリアントは追加される場合がありますが、既存のものが改名されたり、別の用途に転用されたりすることはありません。3 種類の認証情報は、対処方法が異なるため意図的に区別されています。no_creds は認証情報が見つからなかったこと、invalid_creds は認証情報の解決後に AWS が拒否したこと（キーのローテーション後によく見られます）、expired_creds は一時セッションの期限切れを意味します。expired_creds は認証情報の取得元を問わず使われます。AWS は、SSO 由来のセッション、aws_assume_role セッション、ウェブ ID セッションのいずれに対しても、同じ ExpiredToken ラッパーを返すためです。そのため、メッセージでは SSO と決めつけず、両方の対処方法を示します。sso_expired は、botocore の SSO トークンプロバイダーを具体的に示すエラーに限って使用します。malformed_json は、標準出力が { または [ で始まり、解析に失敗したことを意味します。つまり、--query が正当に生成するスカラー出力ではなく、切り詰められたレスポンスを示します。

ベストエフォート（マイナーリリースまたはパッチリリースで変更される可能性があります）：

• エラーメッセージの文言。 「プロファイル 'X' の SSO セッションの有効期限が切れています。aws_login_start を呼び出してください...」のような文字列は、わかりやすさを高めるために調整される場合があります。正規表現で error テキストを照合するのではなく、errorKind または構造化エンベロープを基準にしてください。
• suggestion の文言――認識された AWS エラーコードから導かれる、1 行の対処方法です。suggestion があるかどうかはエラーコードによって決まりますが、文そのものは調整される場合があります。このテキストではなく、errorKind に基づいて分岐してください。これは error の末尾にも重複して含まれるため、両方を読む呼び出し元は二重に表示しないでください。
• rawBody の内容――診断用の、基盤となる aws CLI の標準エラー出力／標準出力です。形式は、インストールされているバージョンの CLI が出力する内容に従います。
• command 文字列――結果とともに表示される、人が読めるコマンドです。引数の順序と、正確な秘匿値のスタブ形式（<redacted len=N>）は変わる場合があります。これはサーバーが実行されるホストのシェル向けに引用符で囲まれます。POSIX シェル、または Windows 上の PowerShell が対象です。cmd.exe では正しく動作しません。引用符の付け方にかかわらず、&、|、改行がそのまま有効だからです。また Windows 上の Git Bash でも正しく動作しません。単一引用符を含む値では引用符が失われ、誤った値が渡されるためです（現実的な例は Buckets[?Name=='prod'].Name です。この場合、実行可能なコマンドになるのではなく、無効な JMESPath になります）。 command を解析するのではなく、commandArgv を使用してください。 command を含むすべてのエンベロープには、同じ呼び出しを正確なトークンの配列で表した commandArgv も含まれます。トークンは引用符なしで、エントリー 0 は表示されるバイナリ、その後は引数ごとに 1 エントリーです。文字列は配列から生成されるため、同じように秘匿化されます。サーバーが実際に起動するのはこれであり（シェルは一切介在しません）、解析し直す必要はなく、想定外のシェルによって再解釈されることもありません。実行する必要がある場合は、ご利用のシェル向けに引用符を付け直してください。文字列形式は読みやすくするためのものであり、契約となるのは配列です。
• ツールの「説明」 — モデルに提示される文章です。これを改善しても、互換性は損なわれません。

非推奨化ポリシー： 安定した形式を破壊的に変更するにはメジャーバージョンの更新が必要です。非推奨化はまずマイナーバージョンで行います（古い形式は引き続き動作し、新しい形式が併せて利用可能になります）。削除は次のメジャーバージョンで予定されます。非推奨化と削除の両方を CHANGELOG.md に記載します。

開発

npm test は単体テストと統合テストの両方を実行します。統合テストスイートは、AWS CLI のスタブとして動作するローカルの fake-aws サブプロセスを起動します。AWS の認証情報やネットワークアクセスは不要です。*.realcli.test.ts という名前のスイートは、実際の AWS CLI を使って fake を検証します。使い捨てのキーを使用して、PATH 上の AWS CLI v2 をプロセス内エンドポイント 127.0.0.1 に接続し、それ以外のすべてのアドレスは到達不能なプロキシにルーティングするため、マシンの外部に通信が出ることはありません。CLI の起動が数回だけ必要なテストは、毎回 npm test で実行され、CLI v2 がインストールされていない場合はスキップされます。実際のタイムアウトや再試行を待つテストでは、release.sh が設定する AWS_MCP_REAL_CLI_TESTS=1 も必要です。実際の AWS 認証情報が必要なのは、環境変数 AWS_MCP_LIVE_TESTS で制御されるライブテストのみで、通常の npm test の実行ではスキップされます。

ライセンス

MIT