LocalStack MCP Server

Let an AI agent manage and interact with LocalStack on your machine.

LocalStack emulates the cloud on your local machine so software teams and AI agents can validate security, quality, and reliability faster and more safely than the cloud allows. This Model Context Protocol (MCP) server lets any MCP client (Cursor, Claude, VS Code, and more) start LocalStack, deploy infrastructure, and debug your local cloud in natural language.

Quick start

Set up the server in your MCP client with the interactive wizard:

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

The wizard detects your installed clients, asks how you want to run the server, and writes the configuration for you. You need a LocalStack Auth Token; the wizard reads LOCALSTACK_AUTH_TOKEN from your environment or asks for it. For the full options, prerequisites, and manual setup, see Installation.

What you can ask your agent

Once the server is configured, talk to LocalStack through your agent in natural language:

• "Start LocalStack and deploy the Terraform project in ./infra, then tell me which resources came up."
• "My Lambda calls are failing. Read the LocalStack logs, find the permission errors, and generate an IAM policy that fixes them."
• "Inject 500ms of latency into DynamoDB and confirm my retry logic still works."
• "Search the LocalStack docs for how to enable S3 event notifications and summarize the steps."

How it works

The server connects MCP-compatible apps directly to your local LocalStack environment and its emulated AWS services, so your assistant can operate the stack securely without custom scripts or manual setup.

This server eliminates custom scripts and manual LocalStack management. Your agent can:

• Start, stop, restart, and monitor LocalStack for AWS container status with built-in auth.
• Deploy CDK, Terraform, and SAM projects with automatic configuration detection.
• Search LocalStack documentation for guides, API references, and configuration details.
• Parse logs, catch errors, and auto-generate IAM policies from violations.
• Inject chaos faults and network effects into LocalStack to test system resilience.
• Manage LocalStack state snapshots via Cloud Pods for development workflows.
• Export, import, inspect, and reset LocalStack state locally with Export & Import State file-based workflows.
• Install, remove, list, and discover LocalStack Extensions from the marketplace.
• Launch and manage Ephemeral Instances for remote LocalStack testing workflows.
• Replicate external AWS resources into LocalStack with AWS Replicator so IaC stacks can resolve shared dependencies locally.
• Inspect LocalStack application flows with App Inspector traces, spans, events, payload metadata, and IAM policy evaluations.
• Start repeatable LocalStack workflows from ready-made MCP prompts, including infrastructure validation and integration test generation.

Tools

This server provides your AI with dedicated tools for managing your LocalStack environment:

Prompts

Prompts are user-selected workflow templates exposed by MCP clients as slash commands or quick actions. They frame multi-step LocalStack tasks so the assistant follows the same phases, evidence requirements, and reporting format every time.

Installation

Set up with the wizard (recommended)

The fastest way to install the MCP server is the interactive setup wizard:

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

The wizard:

• lets you choose how to run the server (npx on your machine, or the self-contained Docker image),
• checks the prerequisites (Node.js, Docker) and tells you how to fix anything missing,
• picks up your LOCALSTACK_AUTH_TOKEN from the environment, or asks for it,
• lets you pass extra LocalStack config (e.g. DEBUG=1,PERSISTENCE=1),
• detects your installed MCP clients (Cursor, Antigravity, Claude Code, Claude Desktop, VS Code, Codex, OpenCode, Amazon Q CLI) and writes the right configuration for each one you select.

It can also run fully non-interactively, e.g. in dotfiles or scripts:

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

To remove the server from your clients again:

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

Run npx -y @localstack/localstack-mcp-server init --help for all options.

Prerequisites

• Docker installed and running. The MCP server manages the LocalStack container directly through the Docker API.
• cdklocal, tflocal, or samlocal installed in your system path if you want to deploy CDK, Terraform, or SAM projects
• Snowflake CLI (snow) installed in your system path if you want to use the Snowflake tool
• A valid LocalStack Auth Token configured as LOCALSTACK_AUTH_TOKEN (required for all MCP tools)
• Node.js v20 or higher installed in your system path

Run with npx

Add the following to your MCP client's configuration file (e.g., ~/.cursor/mcp.json). This configuration uses npx to run the server, which will automatically download and install the package if needed. The server manages LocalStack through your Docker daemon; any deployment CLIs used by tools run from your host PATH.

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

All LocalStack MCP tools require LOCALSTACK_AUTH_TOKEN to be set. You can get your LocalStack Auth Token by following the official documentation.

Run from source

If you installed from source, change command and args to point to your local build:

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

Run with Docker

The localstack/localstack-mcp-server Docker image bundles Terraform/tflocal, CDK/cdklocal, SAM/samlocal, and the Snowflake CLI. The only required host dependency is Docker. The container uses the mounted Docker socket to run LocalStack as a sibling container on the host; state lives in a named Docker volume (localstack-mcp) unless LOCALSTACK_VOLUME_DIR points at a host directory.

If you use the deployer tool with local Terraform, CDK, or SAM projects, bind-mount those project paths into the MCP container and pass the in-container path to the tool. The simplest convention is to mount projects at the same absolute path they use on the host.

{
  "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>" }
    }
  }
}

See docs/DOCKER.md for the run command, MCP client config, IaC project mounts, CDK notes, and troubleshooting.

LocalStack configuration

Migration notes (CLI-free lifecycle)

Since v0.6.0 the MCP server no longer uses (or requires) the localstack CLI. The LocalStack container is created directly through the Docker Engine API. Behavioral differences from CLI-driven starts:

• ~/.localstack/*.env config profiles and DOCKER_FLAGS are not read at start. Pass configuration through the envVars argument of the localstack-management start action, or set LOCALSTACK_-prefixed variables in the MCP server's environment (LocalStack aliases LOCALSTACK_<NAME> to <NAME> natively).
• Besides LOCALSTACK_*/PROVIDER_OVERRIDE_*, only a curated set of common unprefixed config variables is forwarded from the host environment (DEBUG, LS_LOG, SERVICES, PERSISTENCE, EAGER_SERVICE_LOADING, ENFORCE_IAM, IAM_SOFT_MODE, EXTENSION_AUTO_INSTALL, APP_INSPECTOR, DNS_ADDRESS, MAIN_DOCKER_NETWORK, and the LAMBDA_*/CFN_*/SNOWFLAKE_*/SF_* families).
• Port 443 is published by default. If something else uses port 443 locally, set GATEWAY_LISTEN=:4566 to skip it.
• If you previously used lstk, note the container the server creates is named localstack-main (externally started localstack-aws containers are still detected and managed; restart preserves their name, image, and volume).

For AWS Replicator-specific source credentials, you can use the AWS_REPLICATOR_SOURCE_ prefixed variants instead of the unprefixed variants. Do not mix the prefixed and unprefixed source credential groups; when any AWS_REPLICATOR_SOURCE_ variable is set, the Replicator tool reads the source configuration only from that group.

Contributing

Built on the XMCP framework, you can add new tools by adding a new file to the src/tools directory and documenting it in the manifest.json file.

Pull requests are welcomed on GitHub! To get started:

• Install Git and Node.js
• Clone the repository
• Install dependencies with yarn
• Build with yarn build

MCP Server Tester

This repository includes MCP Server Tester for tool validation in direct mode and LLM host mode.

• Run direct MCP tests (deterministic):
  bash

  yarn test:mcp:direct
  

• Run Gemini-based MCP host evals:
  bash

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

• Open the latest MCP Server Tester HTML report:
  bash

  npx mcp-server-tester open
  

• Run both:
  bash

  yarn test:mcp
  

Notes:

• MCP tests target the lifecycle-aware local server command node dist/cli.js by default.
• LOCALSTACK_AUTH_TOKEN is required for all MCP tool usage and test suites.
• You can override the target command with:
  • MCP_TEST_COMMAND
  • MCP_TEST_ARGS (space-separated arguments)

License

Apache License 2.0