LocalStack MCP Server

[!IMPORTANT] The LocalStack MCP server is currently available as an experimental public preview. For questions, issues or feedback, please utilize the LocalStack Community slack or submit a GitHub Issue

A Model Context Protocol (MCP) server that provides tools to manage and interact with your LocalStack for AWS container for simplified local cloud development and testing. The LocalStack MCP Server provides simplified integration between MCP-compatible apps and your local LocalStack for AWS development environment, enabling secure and direct communication with LocalStack's emulated services and additional developer experience features.

This server eliminates custom scripts and manual LocalStack management with direct access to:

• 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.
• Connect AI assistants and dev tools for automated cloud testing workflows.

Tools Reference

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

[!NOTE] All tools in this MCP server require LOCALSTACK_AUTH_TOKEN.

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

Editor	Installation
Cursor

For other MCP Clients, refer to the configuration guide.

Prerequisites

• LocalStack CLI and Docker installed in your system path
• cdklocal, tflocal, or samlocal installed in your system path for running infrastructure deployment tooling
• A valid LocalStack Auth Token configured as LOCALSTACK_AUTH_TOKEN (required for all MCP tools)
• Node.js v22.x or higher installed in your system path

Configuration

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 & install the package if not already present:

jsonCopy code
{
  "mcpServers": {
    "localstack-mcp-server": {
      "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.

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

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

LocalStack Configuration

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):

  bashCopy code
  yarn test:mcp:direct
  

• Run Gemini-based MCP host evals:

  bashCopy code
  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:

  bashCopy code
  npx mcp-server-tester open
  

• Run both:

  bashCopy code
  yarn test:mcp
  

Notes:

• MCP tests target the local STDIO server command node dist/stdio.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