CloudFormation/CDKをMCPで自動検証する — aws-iac-mcp-serverの使い方
aws-iac-mcp-serverでCloudFormationテンプレートの検証・コンプライアンスチェック・デプロイ失敗のトラブルシュートをClaude Codeから実行する手順を示します。
aws-iac-mcp-serverは、AWS LabsがCloudFormationとCDK向けに公開しているMCPサーバーです。テンプレートの構文チェックからセキュリティのコンプライアンス確認、デプロイに失敗したスタックの原因診断まで、Claude Codeに接続するだけで扱えます。中心はローカルで完結するテンプレート検証です。検証系のツールはAWS認証情報が無くても動きます。
aws-iac-mcp-serverで何ができるか
ツールは大きく3系統です。CloudFormationのvalidate_cloudformation_templateとcheck_cloudformation_template_complianceはテンプレートをローカルで検証します。troubleshoot_cloudformation_deploymentは失敗したスタックの原因をCloudTrailの記録と突き合わせて診断します。CDK側はsearch_cdk_documentationとsearch_cdk_samples_and_constructs、cdk_best_practicesがドキュメントとコード例、ベストプラクティスを検索します。生成したテンプレートをデプロイ前に検証したいときも、失敗したあとに原因を追いたいときも、同じサーバーで完結します。
前提条件とセットアップ
uvと、uv python install 3.10で入るPython 3.10が前提です。テンプレート検証だけならAWS認証情報は不要ですが、デプロイ失敗の診断にはIAM権限を持つ認証情報が要ります。認証情報はaws configureで設定するか、AWS_ACCESS_KEY_ID等の環境変数で直接渡す方法もあります。
claude mcp add --env AWS_PROFILE=readonly-profile \
--env FASTMCP_LOG_LEVEL=ERROR \
--transport stdio aws-iac \
-- uvx awslabs.aws-iac-mcp-server@latestWindowsではuvx単体コマンドが無いため、uv tool run --from awslabs.aws-iac-mcp-server@latest awslabs.aws-iac-mcp-server.exeという形でコマンドを組み立てます。.mcp.jsonでは次のような形になります。
{
"mcpServers": {
"awslabs.aws-iac-mcp-server": {
"command": "uv",
"args": [
"tool", "run", "--from",
"awslabs.aws-iac-mcp-server@latest",
"awslabs.aws-iac-mcp-server.exe"
],
"env": { "AWS_PROFILE": "your-aws-profile" }
}
}
}FASTMCP_LOG_LEVEL=ERRORは起動時のログを抑える設定で、必須ではありません。
CloudFormationテンプレートを検証する
validate_cloudformation_templateはcfn-lintを使い、構文エラーや無効なプロパティ、スキーマ違反を行番号付きの修正案とともに返します。パラメータはtemplate_content(必須)、regions、ignore_checksの3つです。regionsを指定すると、そのリージョン固有のプロパティ制約も検証されます。特定のチェックだけ除外したいときは、ignore_checksにcfn-lintのチェックID(例: W2001)を渡します。AIが生成したテンプレートを、デプロイに送る前にその場でエラー検出する用途に向きます。check_cloudformation_template_complianceはこれとは別のツールです。cfn-guardでAWS Guard Rules RegistryとControl Tower proactive controlsに照らし、セキュリティ・コンプライアンス違反を検出します。暗号化の未設定やパブリックアクセスの許可のように、構文チェックだけでは拾えない設計レベルの問題が対象です。サーバーに同梱されたルールセットが対象で、組織独自のカスタムルールは追加できません。CloudFormationドキュメントを検索するsearch_cloudformation_documentationも同じ系統のツールです。リソースタイプやプロパティ、テンプレート構文について、公式ドキュメントの知識ベースから該当箇所を返します。AWS::Lambda::Functionのプロパティを確認しながらテンプレートを書く、といった調べ物に向きます。
デプロイに失敗したスタックの原因を診断する
troubleshoot_cloudformation_deploymentはstack_nameとregionを渡すと、30種類以上の既知の失敗パターンと突き合わせて原因を分析します。手作業でCloudFormationコンソールのイベントタブを遡って原因を探す手間を、この1回のツール呼び出しで代替できます。include_cloudtrail(既定でtrue)を有効にしておくと、CloudTrailの該当イベントへの深いリンクも返します。IAM側にはcloudformation:DescribeStacks・DescribeStackEvents・DescribeStackResourcesとcloudtrail:LookupEventsの読み取り権限が要ります。書き込み権限は不要です。
CDKのドキュメントとベストプラクティスを検索する
search_cdk_documentationはCDK APIリファレンス・ベストプラクティスガイド・コードサンプル・CDK-NAGの検証ルールを横断検索します。クエリはDynamoDB AND tableのようにブール演算子で絞り込め、aws-s3.Bucketのような具体的なコンストラクト名を含めると精度が上がります。search_cdk_samples_and_constructsはlanguageパラメータ(既定typescript)でTypeScript・Python・Java・C#・Goのサンプルを絞り込めます。cdk_best_practicesはパラメータなしで、アプリ設定・コーディング・コンストラクト・セキュリティ・テストの各観点のベストプラクティスをまとめて返します。CDKのAPIは頻繁に更新されるため、モデルの学習データより現行のドキュメントを直接検索するほうが実装との齟齬が出にくくなります。
使ってみる — 自然言語の指示例
実際の指示はそのまま自然文で構いません。「このCloudFormationテンプレートを検証して」とテンプレート本文を貼ればvalidate_cloudformation_templateが呼ばれます。「セキュリティとコンプライアンスをチェックして」と続ければcheck_cloudformation_template_complianceが走ります。「my-app-stackというスタックがus-east-1で失敗した原因を教えて」のように具体的なスタック名とリージョンを添えると、troubleshoot_cloudformation_deploymentが診断結果とCloudTrailへのリンクを返します。CDK側でも同様です。「S3バケットの暗号化のCDKサンプルを探して」と聞けばsearch_cdk_samples_and_constructsが動き、「Lambda関数のCDKベストプラクティスを教えて」ならcdk_best_practicesが該当します。テンプレートの本文をそのままチャットに貼るだけで、コマンドを覚える必要がありません。
ドキュメントページの全文取得とデプロイ前バリデーション
検索結果からさらに詳細を読みたいときはread_iac_documentation_pageが使えます。検索でヒットしたCDKやCloudFormationのドキュメントページをURL指定で丸ごとMarkdownに変換します。starting_indexパラメータでページの続きから取得することもできます。長いAPIリファレンスも要約ではなく全文で確認できるのが利点です。デプロイ前の検証をCLI側でも行いたい場合はget_cloudformation_pre_deploy_validation_instructionsが該当します。パラメータは無く、CloudFormationのチェンジセット作成時に働く事前検証機能の使い方をCLIコマンド付きで返します。
権限設計 — 何にAWS認証情報が要るか
| 機能 | 必要なIAM権限 |
|---|---|
| テンプレート検証・コンプライアンスチェック | 必要なIAM権限不要(ローカル検証のみ) |
| デプロイ失敗の診断 | 必要なIAM権限cloudformation:DescribeStacks / DescribeStackEvents / DescribeStackResources |
| CloudTrail連携の深いリンク | 必要なIAM権限cloudtrail:LookupEvents |
読み取り専用の権限だけで全機能が動きます。デプロイ失敗の診断用に付与するIAMポリシーは次の形で十分です。
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"cloudformation:DescribeStacks",
"cloudformation:DescribeStackEvents",
"cloudformation:DescribeStackResources",
"cloudtrail:LookupEvents"
],
"Resource": "*"
}
]
}aws-api-mcp-serverとの役割分担
同じAWS Labsのリポジトリには、AWS CLIの任意のコマンドを実行できるaws-api-mcp-serverもあります。守備範囲は異なります。aws-api-mcp-serverはあらゆるAWSサービスに横断的にコマンドを投げる汎用サーバーで、call_awsが実際にAPIを実行します。aws-iac-mcp-serverはCloudFormationとCDKの作成・検証・トラブルシュートに特化し、任意のAWSコマンドを実行するツールを持ちません。テンプレートの品質を上げる作業はaws-iac-mcp-server、デプロイ後の運用操作はaws-api-mcp-serverと役割を分けると、それぞれの認証情報の権限も用途なりに絞り込めます。両方を同時に接続しても機能は競合しません。テンプレートの検証はaws-iac-mcp-server、検証を通ったあとのaws cloudformation deploy実行はaws-api-mcp-serverに任せる、という使い分けもできます。
権限設計の負荷も違います。aws-api-mcp-serverは書き込み系のAPIをそのまま実行できるため、denylistやelicitationのような追加の防御層が要ります。aws-iac-mcp-serverの持つツールは、テンプレートのローカル検証か、AWSリソースを変更しないDescribe系のAPI呼び出しに限られます。リソースを直接変更するツールが存在しないため、防御の中心はIAM権限をどこまで絞るかよりも、渡す認証情報自体を読み取り専用にすることで足ります。
つまずきやすいポイント
- Docker利用時は認証情報の更新が必要: aws-iac-mcp-serverのDockerイメージは公開レジストリに無く、
docker build -t awslabs/aws-iac-mcp-server .で自分でビルドしてから使います。起動例は一時的なAWS認証情報を.envファイルに書く形を想定しています。トークンの有効期限が切れたらホスト側から更新し直します - コンプライアンスチェックはサーバー同梱ルールが対象:
cfn-guardのカスタムルールを追加する仕組みは無いため、組織独自のガードレールは別途CI等で検証します troubleshootはスタックが存在する前提: 削除済みのスタックはstack_nameを渡しても診断できません。CloudTrailログ側から追う必要があります- IAMロール・ユーザーの権限確認は接続前に済ませる: デプロイ失敗の診断を使うなら、接続前に上記のIAMポリシーが付与済みかを確認しておきます。権限不足のまま呼び出すとツール自体がAWS側のエラーで失敗します
まとめ
aws-iac-mcp-serverは、CloudFormationとCDKのテンプレートをデプロイ前に検証し、失敗したときの原因調査までを1つのMCPサーバーでカバーします。検証系のツールはAWS認証情報が無くても動く点が使いやすさに直結します。診断系だけ読み取り専用のIAM権限を用意すれば十分です。自作のMCPサーバーでチームの手順を組み込みたい場合はMCPサーバー自作ガイド、他のインフラをMCP経由で扱う設計例はKubernetes MCPサーバー、AWS上でのClaude Code運用全般はClaude Platform on AWSが参考になります。