localstack-mcp-server — Claude Code MCP server: how to install
Connects local LocalStack emulators to your AI assistant to deploy cloud infrastructure, inspect logs, and simulate network faults.
claude mcp add --env LOCALSTACK_AUTH_TOKEN=<LOCALSTACK_AUTH_TOKEN> --env AWS_ACCESS_KEY_ID=<AWS_ACCESS_KEY_ID> --env AWS_SECRET_ACCESS_KEY=<AWS_SECRET_ACCESS_KEY> --env AWS_SESSION_TOKEN=<AWS_SESSION_TOKEN> --env AWS_DEFAULT_REGION=<AWS_DEFAULT_REGION> --transport stdio localstack-mcp-server -- npx -y @localstack/localstack-mcp-serverWhat localstack-mcp-server does
This server exposes runtime tools to interact directly with your local LocalStack instance. Using the localstack-management tool, an agent can start, stop, restart, and monitor the health of emulated AWS and Azure stacks.
Deployments run locally through localstack-deployer, which accepts Terraform, CDK, or SAM templates. When calls fail, the assistant can read runtime logs, detect permission violations, and draft corrective IAM policies. It can also introduce artificial latency to test how application code handles timeouts.
Every tool in this server depends on a valid LOCALSTACK_AUTH_TOKEN. Automated deployments will fail unless tflocal, cdklocal, or samlocal are already installed on your machine.
What it helps with
- deploy local infrastructure templates using Terraform, CDK, or SAM
- diagnose permission errors from logs and generate IAM policies
- simulate API latency to evaluate client retry behavior
- export and restore emulator state with Cloud Pods
Example prompts for the agent
- Launch LocalStack, deploy the Terraform files from
./infra, and list the provisioned resources. - Check the failed Lambda execution logs, locate permission errors, and draft an IAM policy to resolve them.
- Add 500ms latency to DynamoDB calls and test if retry handling functions correctly.
How to install localstack-mcp-server
Platform CLI
claude mcp add --env LOCALSTACK_AUTH_TOKEN=<LOCALSTACK_AUTH_TOKEN> --env AWS_ACCESS_KEY_ID=<AWS_ACCESS_KEY_ID> --env AWS_SECRET_ACCESS_KEY=<AWS_SECRET_ACCESS_KEY> --env AWS_SESSION_TOKEN=<AWS_SESSION_TOKEN> --env AWS_DEFAULT_REGION=<AWS_DEFAULT_REGION> --transport stdio localstack-mcp-server -- npx -y @localstack/localstack-mcp-serverReplace <…> with your own values. 6 more environment variables are in the server README
Platform CLI
codex mcp add localstack-mcp-server --env LOCALSTACK_AUTH_TOKEN=<LOCALSTACK_AUTH_TOKEN> --env AWS_ACCESS_KEY_ID=<AWS_ACCESS_KEY_ID> --env AWS_SECRET_ACCESS_KEY=<AWS_SECRET_ACCESS_KEY> --env AWS_SESSION_TOKEN=<AWS_SESSION_TOKEN> --env AWS_DEFAULT_REGION=<AWS_DEFAULT_REGION> -- npx -y @localstack/localstack-mcp-serverReplace <…> with your own values. 6 more environment variables are in the server README
Config file
{
"mcpServers": {
"localstack-mcp-server": {
"command": "npx",
"args": [
"-y",
"@localstack/localstack-mcp-server"
],
"env": {
"LOCALSTACK_AUTH_TOKEN": "<LOCALSTACK_AUTH_TOKEN>",
"AWS_ACCESS_KEY_ID": "<AWS_ACCESS_KEY_ID>",
"AWS_SECRET_ACCESS_KEY": "<AWS_SECRET_ACCESS_KEY>",
"AWS_SESSION_TOKEN": "<AWS_SESSION_TOKEN>",
"AWS_DEFAULT_REGION": "<AWS_DEFAULT_REGION>"
}
}
}
}Replace <…> with your own values. 6 more environment variables are in the server README
Config file
{
"servers": {
"localstack-mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@localstack/localstack-mcp-server"
],
"env": {
"LOCALSTACK_AUTH_TOKEN": "<LOCALSTACK_AUTH_TOKEN>",
"AWS_ACCESS_KEY_ID": "<AWS_ACCESS_KEY_ID>",
"AWS_SECRET_ACCESS_KEY": "<AWS_SECRET_ACCESS_KEY>",
"AWS_SESSION_TOKEN": "<AWS_SESSION_TOKEN>",
"AWS_DEFAULT_REGION": "<AWS_DEFAULT_REGION>"
}
}
}
}Replace <…> with your own values. 6 more environment variables are in the server README
Platform CLI
gemini mcp add -e LOCALSTACK_AUTH_TOKEN=<LOCALSTACK_AUTH_TOKEN> -e AWS_ACCESS_KEY_ID=<AWS_ACCESS_KEY_ID> -e AWS_SECRET_ACCESS_KEY=<AWS_SECRET_ACCESS_KEY> -e AWS_SESSION_TOKEN=<AWS_SESSION_TOKEN> -e AWS_DEFAULT_REGION=<AWS_DEFAULT_REGION> localstack-mcp-server npx -y @localstack/localstack-mcp-serverReplace <…> with your own values. 6 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about localstack-mcp-server
How to install localstack-mcp-server in Claude Code?
Run `claude mcp add --env LOCALSTACK_AUTH_TOKEN=<LOCALSTACK_AUTH_TOKEN> --env AWS_ACCESS_KEY_ID=<AWS_ACCESS_KEY_ID> --env AWS_SECRET_ACCESS_KEY=<AWS_SECRET_ACCESS_KEY> --env AWS_SESSION_TOKEN=<AWS_SESSION_TOKEN> --env AWS_DEFAULT_REGION=<AWS_DEFAULT_REGION> --transport stdio localstack-mcp-server -- npx -y @localstack/localstack-mcp-server`. Replace placeholder values with your LocalStack token and credentials.
What does localstack-mcp-server do?
It lets AI assistants start mock cloud emulators, execute local infrastructure deployments, and troubleshoot runtime issues without touching live cloud providers.
What external CLI tools are needed for deployments?
The deployment tool requires local installations of cdklocal, tflocal, or samlocal in your system environment.
