AWS Resource MCP

Pythonで開発されたローカルMCPサーバーで、AWSアカウントの実際のリソースを読み取り専用で参照するためのものです。

状態

フェーズ9が実装されています。当サーバーは、統一インベントリ、控えめなアクティビティ分析、明示的な診断、経済分析、そして実際の操作ログから生成された最小権限のIAMポリシーを組み合わせています。

Related MCP server: aws-mcp-server

想定範囲

• stdioによるローカルMCPトランスポート。

• 主要リージョン: eu-west-1。

• AWSクエリは読み取り専用かつ最小権限のみ。

• 利用可能なツール: health_check()、listar_recursos_aws()、analizar_actividad_recursos()、diagnosticar_cobertura_aws()、analizar_riesgo_costes()、revisar_free_tier()、およびconsultar_costes_aws()。

• Cost Explorerは、正確な1リクエストに対する一時的な同意を受けるまでブロックされます。

• AWSへのデプロイやCIはありません。

信頼性

フェーズ10では、ローカルでの統合テスト、契約テスト、セキュリティテスト、パフォーマンステスト、MCPプロトコルテストを追加しています。また、インベントリは各SDK呼び出しの前にAWS_MCP_MAX_REQUESTS_PER_TOOL（デフォルト250）を適用します。予算を使い切ると、結果を保持してpartial_request_budget_exhaustedを返します。

継続的インテグレーションは、各プルリクエストでフォーマット、lint、コンパイル、IAMの決定論的検証、ローカルテストを実行します。AWS認証情報を設定したり、AWS操作を実行したりすることはありません。

Codexでの使用

Codexが主要なクライアントです。パッケージのエントリポイントuv run aws-resource-mcpをstdio経由で使用し、AWSプロファイルはリポジトリ外で設定し、「eu-west-1にどんなリソースがありますか？」などの自然言語の質問から始めてください。応答がpartial_pending_consentの場合、Codexは正確な操作を説明し、明示的な承認を待つ必要があります。永続的な同意は作成しません。Codex統合とデモを参照してください。

v0.1.0リリース

最初のバージョンはレビュー準備が整っています。読み取り専用ガード、一時的な同意、Codex統合、CIが含まれています。リリースチェックリストを参照してローカルで検証し、安全なデモを実行してください。

開発

プロジェクトはuvとPython 3.12以降で管理されています。

依存関係のインストール

uv sync

サーバーの実行

uv run aws-resource-mcp

診断のため、モジュールとして実行することもできます:

uv run python -m aws_resource_mcp.server

サーバーはstdioを使用します。MCPクライアントが標準入力と標準出力でメッセージを交換することを想定しています。SDKに含まれるツールを使用してMCP Inspectorで開くことができます:

uv run mcp dev src/aws_resource_mcp/server.py

テストの実行

uv run pytest

IAMポリシーの生成と検証

uv run aws-resource-mcp-generate-iam
uv run aws-resource-mcp-generate-iam --check

生成はローカルで決定論的に行われ、認証情報は使用しません。プロジェクトはAWSでロールやポリシーを作成・変更しません。ポリシーは、無料の操作、同意が必要な読み取り、および最大の組み合わせを分離します。IAM権限は、アプリケーションの同意に代わるものではありません。

AWSインベントリの実行

実際の診断の前に、ローカル設定がどのIDを解決するかを確認します:

aws sts get-caller-identity

その後、デフォルトリージョンeu-west-1でインベントリを実行します:

uv run python -m aws_resource_mcp.aws.inventory

リージョンと共有プロファイルはオプションです:

uv run python -m aws_resource_mcp.aws.inventory --region eu-central-1 --profile example

プロジェクトには鍵は保存されません。Boto3は標準の認証情報解決チェーンを使用します。AWS_PROFILEまたは--profileを指定した場合、リポジトリ外に既に存在するプロファイルのみが選択されます。

MCPツール

health_check

health_check(check_aws=True)は、ローカルの健全性とAWSの到達可能性を分離します。引数なしの場合、保護されたSTS呼び出しを最大1回実行します。check_aws=falseの場合、ネットワークは使用しません。バージョン、トランスポート、登録済みツールとアダプター、リージョン、経済ポリシー、および請求対象となる操作ゼロを返します。状態は次のとおりです:

• ok: サーバーと設定が有効。STSは要求された場合に応答しました。

• degraded: サーバーは動作していますが、認証情報が不足しているか、STSにアクセスできません。

• error: セキュア設定または内部レジストリを初期化できません。

IDは匿名化されます。プリンシパルの一般的なタイプと、存在する場合はマスクされたアカウントのみが保持されます。インベントリ、Resource Explorer、アダプター、CloudTrail、CloudWatchは実行しません。

listar_recursos_aws

リソースを変更せずに、ローカル認証情報で利用可能なAWSインベントリを照会します。パラメータ:

• region: 検索を1つのリージョンに制限します。値がない場合は、利用可能なすべてのカバレッジを使用します。

• services: lambda、s3、ec2、rdsなどのサービスでフィルタリングします。

• include_account_id: 応答からアカウントIDを省略して匿名化を容易にします。

• resource_types: ec2:instanceなどの動的タイプでフィルタリングします。

• query: テキストまたは名前で検索します。

• all_regions: regionが指定されていない場合、有効なリージョンを使用します。

• include_details: details内にサービス固有のメタデータを含めます。

• include_cost_indicators: 実際の支出を主張せずに、潜在的なコストシグナルを含めます。

• confirm_potentially_billable_operations: 権限を付与しなくなったレガシーパラメータ。

• include_activity_summary: 既に取得済みのフィールドのみを使用して短い要約を追加します。CloudTrailやCloudWatchは照会しません。

• consent_request_id、consent_action、approved_services: 一時的で限定されたリクエストを再開またはキャンセルします。

• timeout_seconds: 1〜120秒の設定可能な予算。

MCPクライアントから送信される引数の例:

{
  "region": "eu-west-1",
  "services": ["lambda", "s3"],
  "include_account_id": false,
  "all_regions": true
}

最初の呼び出しは、許可された操作で取得されたリソースを返します。S3、SQS、またはSNSを完了するために課金対象の操作が必要な場合は、partial_pending_consent、pending_operations、および5分で期限切れになるリクエストを返します。2回目の明示的な呼び出しまで、それらの操作は実行されません:

{
  "consent_request_id": "<id devuelto por la primera llamada>",
  "consent_action": "approve",
  "approved_services": ["s3"]
}

承認は1回限りで、元のIDとスコープに紐付けられ、操作、リージョン、リクエストを制限します。検出と拡張は個別に承認されます。追加のページには新しいリクエストが必要です。consent_action: "cancel"はAWSインベントリを実行しません。

状態は、complete_for_requested_scope、partial_pending_consent、partial_timeout、partial_permission_denied、partial_unavailable、consent_cancelled、errorを区別します。空のリストは、照会された時点でサービスが空だったことのみを意味します。

resources、all_resources、resources_by_serviceは、同じ重複排除されたインベントリを表します。各リソースには、id、arn、name、service、resource_type、region、account_id、state、created_at、sources、details、cost_indicators、activityが含まれます。このツールはコストを計算せず、Free Tierを照会せず、書き込み操作を実行しません。

analizar_actividad_recursos

すべてのリソースに対して同じレジストリとモデルを使用して、既知の最後のアクティビティを分析します。services、regions、resource_idsによるフィルターに加えて、inactive_days、lookback_days、include_administrative_events、および設定可能な制限を受け入れます。CloudTrail履歴は90日に制限され、リソースごとではなくリージョンごとに照会されます。

応答は、last_functional_usage_at、last_administrative_activity_at、last_configuration_change_at、last_state_change_atを区別します。best_known_activity_atは常にシグナルのタイプも示します。アクティブな状態、Describe*クエリ、または変更日は、機能的な使用として提示されません。

リソースごとの状態は、active、inactive_candidate、unknown、not_supported、またはerrorです。非アクティブ候補は、レビュー用の単なる項目です。十分な経過時間、関連するソースの参照、矛盾する最近の証拠がないことが必要です。権限がない、ソースが不十分、または関係が曖昧な場合、偽の非アクティブ確信ではなくunknownになります。

CloudWatchは機能的なメトリクスを提供する可能性がありますが、GetMetricData、GetMetricStatistics、ListMetricsは潜在的に課金対象として登録され、ブロックされています。include_paid_sources=trueは構造化された説明を要求するだけです。同意を意味するものではなく、このフェーズではそれらの操作を決して実行しません。

diagnosticar_cobertura_aws

リソースを列挙せずに、MCPが実際に何を参照できるかを説明します。servicesとregionsのフィルターを受け入れ、権限、アクティビティ、または経済ポリシーのセクションを省略できます。

STS、有効なリージョン、既存のResource Explorerインデックス、アダプターのレジストリと機能、無料のアクティビティソース、ブロックされた操作をチェックします。チェックは実行ごとに5リージョン、CloudTrailのサンプルに制限され、CloudWatch呼び出しはありません。

カバレッジ状態は、available、partial、unavailable、not_configured、permission_denied、blocked_by_cost_policy、not_supported、not_checked、errorを区別します。ポリシーで許可されていると宣言された操作は、証明されたIAM権限としては提示されません。診断では、それをテストするためにサービスインベントリを実行しません。

例:

{
  "services": ["ec2", "rds"],
  "regions": ["eu-west-1"],
  "include_activity_sources": true
}

制限は、影響、MCPが続行できるかどうか、権限が不足しているかどうか、解決に書き込みが必要かどうか、コストが発生する可能性があるかどうかを示します。診断は、提案されたアクションを決して実行しません。

analizar_riesgo_costes

インベントリのインジケーターと、オプションで共通のアクティビティパイプラインを使用してリソースに優先順位を付けます。none_detected、low、medium、high、critical、またはunknown、説明可能なスコア、実行不可能な推奨事項を返します。シグナルは支出を確認せず、none_detectedはコストがゼロであることを意味しません。

include_free_tier=trueは、公式のFree Tierデータを追加します。include_actual_cost=trueは、Cost Explorerの同意を準備するだけです。クエリは実行しません。

revisar_free_tier

AWSが無料と文書化しているGetFreeTierUsageとGetAccountPlanStateを照会します。月次制限、予測、プラン、クレジットを分離します。権限、更新遅延、オファーの枯渇、または適格性の違いにより、部分的な情報または不明な情報を返す場合があります。特定のリソースが無料であるとは主張しません。

consultar_costes_aws

期間と正確なフィルターに対して、集計されたGetCostAndUsageクエリを準備します。最初の呼び出しはAWS操作をゼロ回実行し、メインビューに対するリクエストあたり0.01 USDの公開価格を含む一時的なリクエストを返します。consent_action="approve"を使用した2回目の呼び出しは、最大1ページを実行します。追加のページごとに新しい同意が必要です。cancelはAWSを呼び出しません。

粒度はMONTHLYまたはDAILYにできます。end_dateは排他的です。予測、リソースごとの詳細、リンクされたアカウント、カスタムビリングビューは、このフェーズでは実装されません。

AWSインベントリ

Boto3はAWSの公式Python SDKです。インベントリ層は以下を使用します:

• STS GetCallerIdentityを使用して、アカウントと実効IDを特定します。

• EC2 DescribeRegionsを使用して、有効なリージョンのみを検出します。

• Resource Explorerを使用して、既存のインデックスとビューを介して、サポートされているリソースとタイプを動的に検出します。

• Lambda、S3、EC2/EBS/VPC、RDS/Aurora、DynamoDB、ECS/Fargate、API Gateway、CloudFormation、SQS、SNS、IAM、CloudFront、Route 53用の共通アダプターレジストリ。

• CloudTrail LookupEventsを使用して、過去90日間のリージョナルな無料の管理イベント履歴を取得します。

LambdaとS3は最初に実装されたサービスですが、特別なアーキテクチャパスはもう保持していません。すべてのアダプターは、同じコントラクトを使用してメタデータ、Boto3操作、スコープ、タイプ、詳細、インジケーターを宣言します。特定の詳細はdetails内にのみ存在します。

結果はARN、またはARNがない場合はタイプ、リージョン、識別子/名前で重複排除されます。アグリゲーターインデックスが優先されます。ローカルインデックスの場合、結果が結合され、カバレッジは部分的になります。Resource Explorerが利用できない場合、検出をサポートする選択されたすべてのアダプターが実行されます。

認証情報がない、またはアカウントを特定できない場合は、インベントリではグローバルエラーですが、ローカルヘルスではdegraded状態にすぎません。診断はローカルチェックを保持し、AWSに依存するチェックを安全にスキップします。

すべてのBoto3呼び出しは、まず中央ログを通過します。未登録の操作、書き込み操作、またはコスト不明の操作はブロックされます。free-onlyモードはプロセス全体を通じてアクティブのままです。S3、SQS、SNSはリクエストを計上できます。それらの列挙は保留中として表示され、正確な一時的なgrantのみが実行を許可します。ガードは一意の操作と実際のリクエストを別々にカウントします。

MCPクライアントの例: 「アカウントにどのようなリソースがありますか?」、「eu-west-1のEC2インスタンスを一覧表示」、「webという名前のリソースを検索」、「デプロイされたRDSタイプを表示」。Resource Explorerは広範なカバレッジを提供しますが、普遍的なものではありません。

ドキュメント

• アーキテクチャ

• 決定事項

• フェーズ

• 進捗

• ゼロコストポリシー

• サービスアダプター

• アクティビティ分析

• 診断とカバレッジ

• インベントリ同意フロー

• 経済分析、Free Tier、実際のコスト

• 最小特権IAM

• IAM権限マトリックス

• 手動IAM設定