localstack-mcp-server

重要

LocalStack MCP サーバーは現在、試験的なパブリックプレビューとして提供されています。質問、問題、フィードバックについては、LocalStack Community slack をご利用いただくか、GitHub Issue を送信してください。

LocalStack はクラウドをお使いのローカルマシン上でエミュレートするため、ソフトウェアチームや AI エージェントは、実際のクラウドよりも迅速かつ安全にセキュリティ、品質、信頼性を検証できます。この Model Context Protocol（MCP）サーバーを使うと、あらゆる MCP クライアント（Cursor、Claude、VS Code など）から、自然言語で LocalStack の起動、インフラストラクチャのデプロイ、ローカルクラウドのデバッグを行えます。

クイックスタート

対話式ウィザードで、MCP クライアントにサーバーをセットアップします。

npx -y @localstack/localstack-mcp-server init

ウィザードは、インストールされているクライアントを検出し、サーバーの実行方法を尋ね、設定を書き込みます。LocalStack Auth Token が必要です。ウィザードは環境から LOCALSTACK_AUTH_TOKEN を読み取るか、入力を求めます。すべてのオプション、前提条件、手動セットアップについては、インストールを参照してください。

エージェントに依頼できること

サーバーを設定したら、エージェントを通じて自然言語で LocalStack とやり取りできます。

• 「LocalStack を起動して ./infra の Terraform プロジェクトをデプロイし、どのリソースが立ち上がったか教えて。」
• 「Lambda の呼び出しが失敗している。LocalStack のログを読んで権限エラーを見つけ、それを修正する IAM ポリシーを生成して。」
• 「DynamoDB に 500ms のレイテンシーを注入して、リトライロジックがまだ機能するか確認して。」
• 「S3 イベント通知を有効にする方法を LocalStack のドキュメントで検索し、手順を要約して。」
• 「LocalStack の Azure エミュレーターを起動し、リソースグループとストレージアカウントを作成し、./data/sample.csv を新しい BLOB コンテナーにアップロードして。」

仕組み

このサーバーは、MCP 互換アプリをローカルの LocalStack 環境とそのエミュレートされた AWS サービスに直接接続するため、アシスタントはカスタムスクリプトや手動セットアップなしでスタックを安全に操作できます。

このサーバーは、カスタムスクリプトと手動での LocalStack 管理を不要にします。エージェントは次のことができます:

• 組み込みの認証を使用して、AWS、Snowflake、Azure エミュレーター向けの LocalStack を起動、停止、再起動、監視します。
• 自動構成検出により、CDK、Terraform、SAM プロジェクトをデプロイします。
• LocalStack のドキュメントでガイド、API リファレンス、構成の詳細を検索します。
• ログを解析し、エラーを検出し、違反から IAM ポリシーを自動生成します。
• LocalStack にカオス障害とネットワーク効果を注入し、システムの復元力をテストします。
• 開発ワークフロー向けに、Cloud Pods を介して LocalStack の状態スナップショットを管理します。
• Export & Import State のファイルベースのワークフローで、LocalStack の状態をローカルでエクスポート、インポート、検査、リセットします。
• マーケットプレイスから LocalStack Extensions をインストール、削除、一覧表示、検出します。
• リモートの LocalStack テストワークフロー向けに Ephemeral Instances を起動および管理します。
• AWS Replicator を使用して外部の AWS リソースを LocalStack に複製し、IaC スタックが共有依存関係をローカルで解決できるようにします。
• App Inspector のトレース、スパン、イベント、ペイロードメタデータ、IAM ポリシー評価で LocalStack アプリケーションのフローを検査します。
• インフラストラクチャの検証や統合テストの生成など、すぐに使える MCP プロンプトから再現可能な LocalStack ワークフローを開始します。

ツール

このサーバーは、LocalStack 環境を管理するための専用ツールを AI に提供します:

メモ

この MCP サーバーのすべてのツールには LOCALSTACK_AUTH_TOKEN が必要です。 | ツール名 | 説明 | 主な機能 | | :-------------------------------------------------------------------------------- | :------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | localstack-management | AWS、Snowflake、Azure スタック向けの LocalStack ランタイム操作を管理します | - 起動、停止、再起動、ステータス確認を実行
- LocalStack 認証トークンを統合
- カスタム環境変数を注入
- リアルタイムのステータスを確認し、ヘルスモニタリングを実行 | | localstack-deployer | AWS 環境向けに LocalStack へのインフラストラクチャデプロイを処理します | - CDK、Terraform、SAM ツールを自動実行してインフラストラクチャをローカルにデプロイ
- 変数サポートによるパラメーター化されたデプロイを有効化
- デプロイ結果を処理して表示
- システムパスに cdklocal、tflocal、または samlocal がインストールされている必要があります | | localstack-logs-analysis | トラブルシューティングとインサイトのために LocalStack for AWS のログを分析します | - サマリー、エラー、リクエスト、生データなど複数の分析オプションを提供
- 特定のサービスとオペレーションでフィルタリング
- API 呼び出しメトリクスと失敗の内訳を生成
- エラーをインテリジェントにグループ化し、パターンを特定 | | localstack-iam-policy-analyzer | IAM ポリシーの管理と違反の修復を処理します | - enforced、soft、disabled モードを含む IAM 適用レベルを設定
- 権限関連の違反をログで検索
- 検出されたアクセス失敗から IAM ポリシーを自動生成
- 有効な LocalStack Auth Token が必要 | | localstack-chaos-injector | システムのレジリエンステストのためにカオス実験のフォールトを注入および管理します | - サービスフォールトルールの注入、追加、削除、クリア
- ネットワークレイテンシ効果を設定
- サービス、リージョン、オペレーションによる包括的なフォールトターゲティング
- カオス実験のための組み込みワークフローガイダンス
- 有効な LocalStack Auth Token が必要 | | localstack-cloud-pods | 開発ワークフロー向けのリモート LocalStack Cloud Pods を管理します | - 現在の状態を Cloud Pod として保存
- 以前に保存した Cloud Pod を即座にロード
- リモートクラウドベースのストレージから Cloud Pod を削除
- これは管理されたリモート状態スナップショットに使用し、ローカルのエクスポート/インポートファイルには使用しないでください
- 有効な LocalStack Auth Token が必要 | | localstack-state-management | ローカルファイルベースの LocalStack 状態エクスポート/インポートワークフローを管理します | - LocalStack State REST API を介して LocalStack の状態をディスク上のローカルファイルにエクスポート
- ローカルファイルから LocalStack の状態をインポート
- 現在の LocalStack 状態を JSON メタモデルデータとして検査
- すべての状態または選択したサービスのみをリセット
- エクスポート、リセット、検査でサービスレベルの粒度をサポート
- これはローカルディスクのワークフローに使用し、リモートクラウドベースのスナップショットには Cloud Pods を使用してください
- 有効な LocalStack Auth Token が必要 | | localstack-extensions | LocalStack Extensions のインストール、アンインストール、一覧表示、検出を行います | - 実行中のコンテナ内でインストール済み拡張機能を管理（list、install、uninstall）
- LocalStack Extensions マーケットプレイスを閲覧（available）
- 有効な LocalStack Auth Token が必要 | | localstack-ephemeral-instances | クラウドホスト型の LocalStack Ephemeral Instances を管理します | - 一時的なクラウドホスト型 LocalStack インスタンスを作成し、エンドポイント URL を取得
- 利用可能なエフェメラルインスタンスの一覧表示、ログの取得、インスタンスの削除
- 作成時にライフタイム、拡張機能のプリロード、Cloud Pod のプリロード、カスタム環境変数をサポート
- 有効な LocalStack Auth Token が必要 | | localstack-aws-client | LocalStack for AWS コンテナ内で AWS CLI コマンドを実行します | - 実行中のコンテナ内で awslocal を介してコマンドを実行
- シェルチェーンをブロックするためにコマンドをサニタイズ
- LocalStack のカバレッジエラーを自動検出し、ドキュメントへのリンクを表示 | | localstack-azure-client | LocalStack for Azure エミュレーターに対して Azure CLI（az）コマンドを実行します | - マシンにインストールされた Azure CLI を独自のプロファイルで実行し、Azure ログインは決して使用しません
- シェル構文や、プロファイルの変更、ソフトウェアのインストール、終了しないコマンドをブロック
- az extension add でインストールした拡張機能を使用
- Azure CLI と有効な LocalStack Auth Token が必要 | | localstack-aws-replicator | 外部の AWS リソースを実行中の LocalStack インスタンスにレプリケートします | - リソースタイプと識別子または ARN を指定して単一リソースのレプリケーションジョブを開始
- パスプレフィックス配下の SSM パラメーターなど、バッチレプリケーションジョブを開始
- ジョブ ID でジョブステータスをポーリングし、既存のジョブを一覧表示
- 実行中の Replicator 拡張機能がサポートするリソースタイプを一覧表示
- MCP サーバー環境からソース AWS 認証情報を読み取り、オプションのターゲットアカウントまたはリージョンの上書きをサポート | | localstack-app-inspector | LocalStack アプリケーションのトレース、スパン、イベント、IAM 評価を検査します | - 実行中の LocalStack インスタンスの App Inspector を有効化または無効化
- トレースを一覧表示および検査して AWS のサービス間フローを理解
- スパン、イベント、ペイロードメタデータ、IAM ポリシー評価イベントを詳細に調査
- サービス、リージョン、オペレーション、リソース、ARN、ステータス、時間範囲でフィルタリング
- 有効な LocalStack Auth Token と、接続された LocalStack ライセンスの App Inspector 機能が必要 | | localstack-docs | CrawlChat を介して LocalStack ドキュメントを検索します | - 公開 CrawlChat コレクションを介して LocalStack ドキュメントをクエリ
- ソースリンク付きの的を絞ったスニペットのみを返却
- LocalStack ランタイムを必要とせずに、カバレッジ、構成、セットアップに関する質問への回答を支援 | | localstack-snowflake-client | snow CLI を介して LocalStack Snowflake エミュレーターに対して SQL を実行します | - クエリ文字列または .sql ファイルから SELECT、DDL（CREATE/DROP）、DML（INSERT/UPDATE/DELETE）、SHOW/DESCRIBE ステートメントを実行
- クエリを実行する前に Snowflake 接続を確認
- クエリごとにオプションのデータベース、スキーマ、ウェアハウス、ロールコンテキストを設定
- Snowflake CLI（snow）と有効な LocalStack Auth Token が必要 |

プロンプト

プロンプトは、MCP クライアントがスラッシュコマンドやクイックアクションとして公開する、ユーザーが選択するワークフローテンプレートです。これにより、マルチステップの LocalStack タスクを定型化し、アシスタントが毎回同じフェーズ、証拠要件、レポート形式に従うようになります。

プロンプト名	説明	引数
infrastructure-tester	IaC プロジェクトを LocalStack にデプロイし、宣言されたリソースを実際の AWS プローブと App Inspector の証拠で検証したうえで、決定論的な統合テストを作成して実行します。	iac_path (必須), iac_type, test_language, test_framework, mode, services_focus, user_focus

インストール

ウィザードでセットアップする (推奨)

MCP サーバーをインストールする最も簡単な方法は、対話式のセットアップウィザードです:

npx -y @localstack/localstack-mcp-server init

このウィザードは:

• サーバーの実行方法 (お使いのマシン上の npx、または自己完結型の Docker イメージ) を選択できます。
• 前提条件 (Node.js、Docker) を確認し、不足しているものがあればその修正方法を案内します。
• 環境から LOCALSTACK_AUTH_TOKEN を取得するか、入力を求めます。
• 追加の LocalStack 設定 (例: DEBUG=1,PERSISTENCE=1) を渡すことができます。
• インストールされている MCP クライアント (Cursor、Antigravity、Claude Code、Claude Desktop、VS Code、Codex、OpenCode、Amazon Q CLI) を検出し、選択したそれぞれに適切な設定を書き込みます。

dotfiles やスクリプトなどで、完全に非対話で実行することもできます:

npx -y @localstack/localstack-mcp-server init --method npx --client cursor,claude-code --yes

クライアントからサーバーを再度削除するには:

npx -y @localstack/localstack-mcp-server remove

すべてのオプションについては npx -y @localstack/localstack-mcp-server init --help を実行してください。

前提条件

• Docker がインストールされ、実行されていること。MCP サーバーは Docker API を通じて LocalStack コンテナを直接管理します。
• CDK、Terraform、または SAM プロジェクトをデプロイする場合は、cdklocal、tflocal、または samlocal がシステムパスにインストールされていること
• Snowflake ツールを使用する場合は、Snowflake CLI (snow) がシステムパスにインストールされていること
• Azure ツールを使用する場合は、Azure CLI (az) がシステムパスにインストールされていること (docs/AZURE.md を参照)
• 有効な LocalStack Auth Token が LOCALSTACK_AUTH_TOKEN として設定されていること (すべての MCP ツールで必須)
• Node.js v20 以降がシステムパスにインストールされていること

npx で実行する

MCP クライアントの設定ファイル (例: ~/.cursor/mcp.json) に以下を追加します。この設定では npx を使用してサーバーを実行し、必要に応じてパッケージが自動的にダウンロードおよびインストールされます。サーバーは Docker デーモンを通じて LocalStack を管理します。ツールが使用するデプロイ CLI は、ホストの PATH から実行されます。

{
  "mcpServers": {
    "localstack": {
      "command": "npx",
      "args": ["-y", "@localstack/localstack-mcp-server"],
      "env": {
        "LOCALSTACK_AUTH_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

すべての LocalStack MCP ツールで LOCALSTACK_AUTH_TOKEN の設定が必須です。LocalStack Auth Token は、公式のドキュメントに従って取得できます。

ソースから実行する

ソースからインストールした場合は、command と args をローカルビルドを指すように変更してください:

{
  "mcpServers": {
    "localstack": {
      "command": "node",
      "args": ["/path/to/your/localstack-mcp-server/dist/cli.js"],
      "env": {
        "LOCALSTACK_AUTH_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

Docker で実行する

localstack/localstack-mcp-server Docker イメージには、Terraform/tflocal、CDK/cdklocal、SAM/samlocal、および Snowflake CLI がバンドルされています。ホスト側で必要な依存関係は Docker だけです。コンテナはマウントされた Docker ソケットを使用して、ホスト上で LocalStack を兄弟コンテナとして実行します。状態は、LOCALSTACK_VOLUME_DIR がホストのディレクトリを指していない限り、名前付き Docker ボリューム（localstack-mcp）に保存されます。

deployer ツールをローカルの Terraform、CDK、または SAM プロジェクトで使用する場合は、それらのプロジェクトパスを MCP コンテナにバインドマウントし、コンテナ内のパスをツールに渡してください。最も簡単な方法は、プロジェクトをホスト上で使用しているものと同じ絶対パスにマウントすることです。

{
  "mcpServers": {
    "localstack": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/var/run/docker.sock:/var/run/docker.sock",
        "--add-host",
        "host.docker.internal:host-gateway",
        "--add-host",
        "s3.host.docker.internal:host-gateway",
        "--add-host",
        "snowflake.localhost.localstack.cloud:host-gateway",
        "-e",
        "LOCALSTACK_AUTH_TOKEN",
        "-e",
        "LOCALSTACK_HOSTNAME=host.docker.internal",
        "-v",
        "/Users/you/projects:/Users/you/projects",
        "localstack/localstack-mcp-server:latest"
      ],
      "env": { "LOCALSTACK_AUTH_TOKEN": "<YOUR_TOKEN>" }
    }
  }
}

実行コマンド、MCP クライアントの設定、IaC プロジェクトのマウント、CDK に関する注意事項、トラブルシューティングについては、docs/DOCKER.md を参照してください。

LocalStack の設定

変数名	説明	デフォルト値
LOCALSTACK_AUTH_TOKEN (必須)	MCP サーバーで使用する LocalStack Auth Token	なし
LOCALSTACK_HOSTNAME	ツールが呼び出す LocalStack ゲートウェイのホスト名。Docker 内では host.docker.internal。Azure ツールは常に azure.localhost.localstack.cloud (127.0.0.1) を呼び出すため、ローカルゲートウェイが必要です。	localhost
LOCALSTACK_PORT	ツールが呼び出す LocalStack ゲートウェイのポート。	4566
MAIN_CONTAINER_NAME	Docker ベースのツールで使用する LocalStack コンテナ名を明示的に指定します。未設定の場合、サーバーは localstack-main や localstack-aws などの標準的な LocalStack コンテナ、続いて LocalStack Docker イメージを自動検出します。	自動検出
LOCALSTACK_IMAGE_NAME / IMAGE_NAME	AWS スタックに対して start アクションが起動する Docker イメージ。両方設定されている場合は LOCALSTACK_IMAGE_NAME が優先されます (注意: 単なる IMAGE_NAME はよくある CI 変数です)。	localstack/localstack-pro:latest
LOCALSTACK_VOLUME_DIR	LocalStack コンテナ内の /var/lib/localstack にマウントされるホストディレクトリ。デフォルトでは LocalStack CLI が使用していた OS ごとのキャッシュパスと同じになります (状態は引き継がれます)。Docker 内では localstack-mcp という名前付きボリュームがデフォルトです。	OS ごとのキャッシュディレクトリ
GATEWAY_LISTEN	start のゲートウェイポートバインディングを上書きします (カンマ区切りの [host]:port)。設定すると、暗黙の 443 バインディングはスキップされます。	:4566,:443
DOCKER_HOST	すべてのコンテナ操作で使用される Docker デーモンエンドポイント (unix://、npipe://、tcp://)。	プラットフォームのデフォルトソケット
DOCKER_SOCK	LocalStack コンテナ (Lambda 用) にマウントされる Docker ソケットのホストパス。明示的に設定した場合は存在が検証されます。	/var/run/docker.sock
EXTERNAL_SERVICE_PORTS_START / _END	start 時に外部サービス用に公開される包括的なホストポート範囲。検証されます (1～65535、start ≤ end)。	4510 / 4560
MCP_ANALYTICS_DISABLED	1 に設定すると MCP アナリティクスを無効化します	0
APP_INSPECTOR	LocalStack コンテナ環境で 1 に設定すると、再起動後もデフォルトで App Inspector が有効になります。MCP ツールは実行時に set-status で App Inspector を切り替えることもできます。	0
AWS_ACCESS_KEY_ID (AWS Replicator ツールで必須)	AWS Replicator が外部 AWS リソースを読み取るために使用するソース AWS アクセスキー	なし
AWS_SECRET_ACCESS_KEY (AWS Replicator ツールで必須)	AWS Replicator が外部 AWS リソースを読み取るために使用するソース AWS シークレットアクセスキー	なし
AWS_DEFAULT_REGION (AWS Replicator ツールで必須)	AWS Replicator が使用するソース AWS リージョン	なし
LOCALSTACK_AZURE_IMAGE_NAME	Azure スタックに対して start アクションが起動する Docker イメージ (デフォルトは localstack/localstack-azure:latest)。	最新の Azure イメージ
LOCALSTACK_AZ_PATH	Azure ツールで使用する az ランチャー、または Azure CLI の Python。	PATH 上で検出
LOCALSTACK_AZ_CONFIG_DIR	Azure ツール専用の Azure CLI プロファイルディレクトリ (デフォルトは ~/.localstack/azure/mcp-config-<port>)。~/.azure と重複してはいけません。	~/.localstack/azure 配下
LOCALSTACK_AZ_WORKDIR	Azure ツールが az を実行するディレクトリ。相対ファイルパスはこれを基準に解決されます。	サーバーの作業ディレクトリ
LOCALSTACK_AZ_TIMEOUT_SECONDS	Azure CLI コマンド 1 回あたりの制限時間 (5～3600)。	300
Azure ツールが Azure CLI をどのように実行するかについては、docs/AZURE.md を参照してください。

移行に関する注意事項 (CLI 不要のライフサイクル)

v0.6.0 以降、MCP サーバーは localstack CLI を使用しなくなりました (また必要としません)。LocalStack コンテナは Docker Engine API を通じて直接作成されます。CLI 駆動の起動との動作の違いは以下のとおりです。

• ~/.localstack/*.env 設定プロファイルおよび DOCKER_FLAGS は起動時に読み込まれません。設定は localstack-management の start アクションの envVars 引数を通じて渡すか、MCP サーバーの環境で LOCALSTACK_ プレフィックス付きの変数を設定してください (LocalStack は LOCALSTACK_<NAME> をネイティブに <NAME> へエイリアスします)。
• LOCALSTACK_*/PROVIDER_OVERRIDE_* に加えて、厳選された一般的なプレフィックスなしの設定変数のみがホスト環境から転送されます (DEBUG、LS_LOG、SERVICES、PERSISTENCE、EAGER_SERVICE_LOADING、ENFORCE_IAM、IAM_SOFT_MODE、EXTENSION_AUTO_INSTALL、APP_INSPECTOR、DNS_ADDRESS、MAIN_DOCKER_NETWORK、および LAMBDA_*/CFN_*/SNOWFLAKE_*/SF_* ファミリー)。
• ポート 443 はデフォルトで公開されます。ローカルで他の何かがポート 443 を使用している場合は、GATEWAY_LISTEN=:4566 を設定してスキップしてください。
• 以前に lstk を使用していた場合、サーバーが作成するコンテナの名前は localstack-main であることに注意してください (外部で起動された localstack-aws コンテナは引き続き検出および管理されます。restart はそれらの名前、イメージ、ボリュームを保持します)。

AWS Replicator 固有のソース認証情報には、プレフィックスなしの変数の代わりに AWS_REPLICATOR_SOURCE_ プレフィックス付きの変数を使用できます。プレフィックス付きとプレフィックスなしのソース認証情報グループを混在させないでください。いずれかの AWS_REPLICATOR_SOURCE_ 変数が設定されている場合、Replicator ツールはそのグループからのみソース設定を読み取ります。

コントリビューション

XMCP フレームワーク上に構築されており、src/tools ディレクトリに新しいファイルを追加し、manifest.json ファイルにドキュメント化することで新しいツールを追加できます。

GitHub でのプルリクエストを歓迎します! はじめるには:

• Git と Node.js をインストールする
• リポジトリをクローンする
• yarn で依存関係をインストールする
• yarn build でビルドする

MCP Server Tester

このリポジトリには、ダイレクトモードおよび LLM ホストモードでのツール検証用の MCP Server Tester が含まれています。

• ダイレクト MCP テスト (決定的) を実行する:

  yarn test:mcp:direct
  

• Gemini ベースの MCP ホスト評価を実行する:

  export GOOGLE_GENERATIVE_AI_API_KEY="<your-gemini-key>"
  export LOCALSTACK_AUTH_TOKEN="<your-localstack-auth-token>"
  yarn test:mcp:evals
  

• 最新の MCP Server Tester HTML レポートを開く:

  npx mcp-server-tester open
  

• 両方を実行する:

  yarn test:mcp
  

注意事項:

• MCP テストはデフォルトでライフサイクル対応のローカルサーバーコマンド node dist/cli.js を対象とします。
• LOCALSTACK_AUTH_TOKEN は、すべての MCP ツールの使用およびテストスイートに必要です。
• 対象コマンドは以下で上書きできます:
  • MCP_TEST_COMMAND
  • MCP_TEST_ARGS (スペース区切りの引数)

ライセンス

Apache License 2.0