# localstack-mcp-server

Connects local LocalStack emulators to your AI assistant to deploy cloud infrastructure, inspect logs, and simulate network faults.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 29
- Author: localstack
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/localstack/localstack-mcp-server
- Updated: 2026-10-21
- HTML: https://affpapa.org/en/nevibecode/mcp/localstack-mcp-server

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `LOCALSTACK_AUTH_TOKEN`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_DEFAULT_REGION`, `AWS_REPLICATOR_SOURCE_AWS_ACCESS_KEY_ID`, `AWS_REPLICATOR_SOURCE_AWS_SECRET_ACCESS_KEY`, `AWS_REPLICATOR_SOURCE_AWS_SESSION_TOKEN`, `AWS_REPLICATOR_SOURCE_REGION_NAME`, `AWS_REPLICATOR_SOURCE_ENDPOINT_URL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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 <…> with your own values. 6 more environment variables are in the server README

### Codex

**Platform CLI**
```bash
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-server
```
Replace <…> with your own values. 6 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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

### Gemini CLI

**Platform CLI**
```bash
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-server
```
Replace <…> with your own values. 6 more environment variables are in the server README

## When to use it
- 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
- 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.

## Similar
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872
- [Coder](https://affpapa.org/en/nevibecode/mcp/coder.md) — MCP server · ★ 17160
- [firebase-mcp](https://affpapa.org/en/nevibecode/mcp/firebase-mcp.md) — MCP server · ★ 4481
- [Radar Kubernetes MCP Server](https://affpapa.org/en/nevibecode/mcp/radar-kubernetes-mcp-server.md) — MCP server · ★ 3905
- [Supabase](https://affpapa.org/en/nevibecode/mcp/supabase.md) — MCP server · ★ 2969
- [Microsoft Fabric MCP Server](https://affpapa.org/en/nevibecode/mcp/microsoft-fabric-mcp-server.md) — MCP server · ★ 3799

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md