localstack-mcp-server

The LocalStack MCP Server is a Model Context Protocol (MCP) server for LocalStack, with the goal of enabling AI agents to manage and interact with the LocalStack environment on the local machine, thereby simulating cloud services locally and helping software teams and AI agents validate security, quality, and reliability faster and more safely. The server is currently available as an experimental public preview.

Purpose

• Let MCP clients (such as Cursor, Claude, VS Code, etc.) directly operate the local LocalStack environment and its simulated AWS services through natural language, without writing custom scripts or manually managing LocalStack.

Main Capabilities

• Lifecycle management: start, stop, restart, and monitor LocalStack's AWS, Snowflake, and Azure emulators, with built-in authentication.
• Infrastructure deployment: deploy CDK, Terraform, and SAM projects, with support for automatic configuration detection.
• Documentation retrieval: search LocalStack documentation to obtain guides, API references, and configuration details.
• Logs and permissions: parse logs, capture errors, and automatically generate IAM policies based on violations.
• Fault injection: inject chaos faults and network effects into LocalStack to test system resilience.
• State management: manage LocalStack state snapshots through Cloud Pods; export, import, inspect, and reset LocalStack state locally through file-based import/export workflows.
• Extension management: install, remove, list, and discover LocalStack Extensions from the marketplace.
• Ephemeral instances: start and manage Ephemeral Instances for remote LocalStack testing workflows.
• Resource replication: use AWS Replicator to replicate external AWS resources to LocalStack, enabling IaC stacks to resolve shared dependencies locally.
• Flow inspection: inspect application flows through App Inspector, including traces, spans, events, payload metadata, and IAM policy evaluation.
• Preset prompts: launch repeatable LocalStack workflows from ready-made MCP prompts,including infrastructure validation and integration test generation.

Usage

• Installation through the interactive setup wizard is recommended: the wizard detects installed MCP clients, asks about the desired runtime mode, and automatically writes the configuration. It also checks prerequisites (Node.js, Docker), reads or asks for LOCALSTACK_AUTH_TOKEN from the environment, and can accept additional LocalStack configuration (such as DEBUG=1,PERSISTENCE=1). The wizard also supports fully non-interactive operation, making it convenient to write into dotfiles or scripts; all options can be viewed with npx -y @localstack/localstack-mcp-server init --help.
• Manual configuration: add a configuration to the MCP client configuration file that runs the server with npx. The server manages LocalStack through the Docker daemon.
• Docker method: the localstack/localstack-mcp-server image has Terraform/tflocal, CDK/cdklocal, SAM/samlocal, and Snowflake CLI built in, and the host only needs to have Docker installed; the container runs LocalStack on the host as a sibling container through the mounted Docker socket.
• Run from source: point command and args to a locally built version.
• Built-in tool development: based on the XMCP framework, new tools can be added by adding files in the src/tools directory and recording them in manifest.json.

Prerequisites

• Docker is installed and running.
• If CDK, Terraform, or SAM projects need to be deployed, cdklocal, tflocal, or samlocal must be installed in the system path.
• If Snowflake tools are used, the Snowflake CLI (snow) must be installed in the system path.
• If Azure tools are used, the Azure CLI (az) must be installed in the system path.
• All MCP tools require a valid LocalStack Auth Token, configured as LOCALSTACK_AUTH_TOKEN.
• Node.js v20 or later is requiredInstalled in the system path.

Examples you can ask the agent

• "Start LocalStack and deploy the Terraform project in ./infra, then tell me which resources have started."
• "My Lambda invocation failed. Read the LocalStack logs, find the permission errors, and generate the IAM policies to fix them."
• "Inject a 500ms delay into DynamoDB and confirm that my retry logic still works."
• "Search the LocalStack documentation for how to enable S3 event notifications and summarize the steps."
• "Start the LocalStack Azure emulator, create a resource group and a storage account, and upload ./data/sample.csv to the new blob container."

Migration notes (no CLI lifecycle)

• Since v0.6.0, the MCP server no longer uses or requires the localstack CLI; LocalStack containers are created directly through the Docker Engine API.
• At startup, it no longer reads the ~/.localstack/*.env configuration files and DOCKER_FLAGS; pass configuration through the envVars parameter of the localstack-management start operation, or set LOCALSTACK_ prefixed variables in the MCP server environment.
• Except for LOCALSTACK_* / PROVIDER_OVERRIDE_*, only a curated set of common unprefixed configuration variables is forwarded from the host environment.
• The default published port is 443; if local port 443 is occupied, you can set GATEWAY_LISTEN=:4566 to skip it.
• The container created by the server is named localstack-main; an externally started localstack-aws container will still be detected and managed, and a restart will preserve its name, image, and volumes.
• AWS Replicator-specific source credentials can use the AWS_REPLICATOR_SOURCE_ prefixed variant; do not mix prefixed and unprefixed source credential groups.

Limitations and status

• The server is currently an experimental public preview.
• All MCP tools require LOCALSTACK_AUTH_TOKEN.
• Using the Azure tools, Snowflake tools, and CDK/Terraform/SAM deployment respectively requires the corresponding CLI or tool to be installed in the system path.
• Specific charges, pricing, and platform details are not yet provided.

The project is licensed under the Apache License 2.0, and the repository is on GitHub.