LocalStack MCP Server

Introduction

The LocalStack MCP Server is a Model Context Protocol (MCP) server that connects MCP-compatible clients to your LocalStack environment. With the Azure emulator, it lets your AI agent start and stop the emulator, run Azure CLI commands and Bicep deployments against it, and read its logs, all through natural language prompts.

The Azure CLI commands never reach real Azure: the server runs them in an Azure CLI profile of its own that is logged in to the emulator only, and blocks every other destination (see How the Azure tool stays local).

Note

Azure support requires a LocalStack MCP Server release newer than 0.6.0.

Prerequisites

Before configuring the MCP server, ensure the following are installed and available on your system PATH:

• Node.js (v20 or later) to run npx.
• Docker to run the LocalStack container. The server manages it directly through the Docker API.
• The Azure CLI (az 2.85 or later) for the Azure tool. Check your version with az --version.
• A LocalStack Auth Token whose license covers Azure. All MCP server tools require it.

Installation

The LocalStack MCP Server is published on npm as @localstack/localstack-mcp-server. The recommended approach is to let your MCP client run the server via npx, which downloads and caches the package automatically.

Set up with the wizard

The quickest way to get started is the interactive setup wizard:

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

The wizard asks how you want to run the server, checks the prerequisites, picks up LOCALSTACK_AUTH_TOKEN from your environment or asks for it, and writes the configuration for the MCP clients you select: Cursor, Antigravity, Claude Code, Claude Desktop, VS Code, Codex, OpenCode, and Amazon Q CLI. It can also run non-interactively, for example:

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

Configure your client manually

For any MCP-compatible client, configure a stdio server with the command npx, the arguments -y @localstack/localstack-mcp-server, and LOCALSTACK_AUTH_TOKEN in its environment. If your client uses a JSON configuration file, the entry follows this format:

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

With Claude Code, run:

claude mcp add localstack \
  -e LOCALSTACK_AUTH_TOKEN=<YOUR_TOKEN> \
  -- npx -y @localstack/localstack-mcp-server

Refer to your client’s documentation for the exact location of its MCP configuration file.

Note

The Azure tool only accepts files inside its working directory, which is the directory the server starts in. If your client starts the server in a folder other than your project, add "LOCALSTACK_AZ_WORKDIR": "<your project folder>" to the env block to work with your templates and other local files.

Set up the Azure tool

The Azure tool runs the Azure CLI installed on your machine, because the Azure emulator image doesn’t include one. Besides az itself, it uses a set of Azure CLI extensions and the Bicep CLI, which you install once with:

npx -y @localstack/localstack-mcp-server install-azure-addons

This installs 26 pinned extensions into ~/.localstack/azure/mcp-extensions and a pinned, checksum-verified Bicep into ~/.localstack/azure/bin, and never touches your own ~/.azure. Skip either part with --no-extensions or --no-bicep. Without the add-ons, the core az commands still work; a command that needs an extension, or a .bicep deployment without Bicep, answers with the command above.

Run from the Docker image

The wizard can also set up the server to run from the localstack/localstack-mcp-server Docker image (--method docker), which bundles the Azure CLI, the extensions, and Bicep, so you install none of them. The Azure emulator runs Function Apps and Web Apps in containers of its own and shares their files from its state directory, which only works with a directory on your host: set LOCALSTACK_VOLUME_DIR to one if you deploy them.

Tools

The MCP server exposes the following tools for the Azure emulator. Each tool runs pre-flight checks, such as whether the Auth Token is present and which emulator is running, and returns structured responses.

localstack-management

Manage the lifecycle of the LocalStack container. Set service to azure for the Azure emulator.

Parameter	Type	Required	Description
action	start | stop | restart | status	Yes	The operation to perform
service	aws | snowflake | azure	No	The emulator to manage (default: aws)
envVars	Record<string, string>	No	Extra environment variables passed on start

start runs the localstack/localstack-azure image in a container named localstack-main. status also finds an emulator you started yourself, for example with lstk, and reports its container, version, and license state. Use envVars, or the env block of the server configuration, to pass emulator settings such as LS_AZURE_PORTAL or MSSQL_ACCEPT_EULA when the server starts the emulator.

Example prompts:

• “Start the LocalStack Azure emulator.”
• “Start the Azure emulator with LS_AZURE_PORTAL=1, so I can use the Azure Portal Emulator.”
• “What’s the status of LocalStack?”

localstack-azure-client

Run Azure CLI commands against the Azure emulator.

Parameter	Type	Required	Description
command	string	Yes	The Azure CLI command, without the leading az

Whatever az can do and the emulator implements works, with az’s own validation and --help. That includes Bicep deployments from .bicep and .bicepparam files, and rest calls for operations that az has no command for: an absolute https://management.azure.com/... URL is rewritten to a relative one, so it reaches the emulator. When a command fails, the answer carries az’s own error, a failure class such as not-implemented or bicep-missing, and a hint.

Example prompts:

• “Create a resource group named demo-rg in West Europe, and a storage account in it.”
• “Deploy main.bicep with the parameters in main.bicepparam to the demo-rg resource group.”
• “List every resource in demo-rg.”

localstack-logs-analysis

Read the emulator’s logs.

Parameter	Type	Required	Description
analysisType	summary | errors | requests | logs	No	Type of analysis. Use logs with the Azure emulator.
lines	number	No	Number of log lines to fetch
filter	string	No	Keyword filter (used with logs mode only)

The summary, errors, and requests analyses parse AWS request logs, so with the Azure emulator they refuse and point you to analysisType: logs, which returns the raw log output.

Example prompts:

• “Show me the last 100 lines of the LocalStack logs.”
• “Get the LocalStack logs filtered by ‘Microsoft.Storage’.”

localstack-docs

Search the LocalStack documentation to find guides, API references, and configuration details.

Parameter	Type	Required	Description
query	string	Yes	The search query
limit	number	No	Maximum number of results to return

Example prompts:

• “Search the LocalStack docs for how to enable RBAC enforcement on Azure.”

Tools for the other emulators

The server’s other tools work with the AWS or Snowflake emulator only: localstack-deployer, localstack-aws-client, localstack-iam-policy-analyzer, localstack-chaos-injector, localstack-cloud-pods, localstack-state-management, localstack-extensions, localstack-app-inspector, localstack-aws-replicator, localstack-ephemeral-instances, and localstack-snowflake-client. The ones that talk to the running emulator refuse when they find the Azure emulator, and name the tool to use instead. See LocalStack MCP Server in the AWS docs for those tools.

How the Azure tool stays local

localstack-azure-client runs the Azure CLI installed on your machine, but it never uses your own Azure CLI login and never reaches real Azure:

• Its own CLI profile. az runs with AZURE_CONFIG_DIR set to the tool’s profile (~/.localstack/azure/mcp-config-<port>), registered with a LocalStack cloud and a dummy login. It also gets a private home and temp directory, so commands that write into ~ never touch yours.
• A command policy. Shell syntax, logins, cloud and config changes, extension installs, upgrade, and commands that open a browser, shell, or tunnel or run Docker on your machine are refused. File arguments must stay inside the working directory (LOCALSTACK_AZ_WORKDIR), and never reach ~/.azure, ~/.ssh, ~/.kube, or ~/.docker.
• An allow-list environment. az gets a minimal environment; your AZURE_*, ARM_*, proxy, and CA variables are never passed on.
• An egress guard. Every connection az or Bicep makes goes through a local proxy that allows only the emulator’s names and ports. A call to any other host is refused, and the answer names it.

Long-running creates wait until the resource is ready. If your MCP client gives up on long tool calls, ask the agent to use --no-wait and to poll the resource with show.

Quickstart

Once your MCP client is configured, verify the setup by opening a conversation with your AI agent.

1. Start the Azure emulator

“Start the LocalStack Azure emulator.”

The agent uses the localstack-management tool with service: azure and confirms the status.

2. Create resources

“Create a resource group named demo-rg in West Europe, and a storage account named demostorage01 in it.”

The agent runs group create and storage account create through localstack-azure-client and returns the results.

3. Deploy a Bicep template

“Deploy main.bicep to demo-rg.”

The agent runs deployment group create with your template, which must be inside the tool’s working directory.

4. Check the logs

“Show me the last 50 lines of the LocalStack logs.”

The agent fetches the raw emulator logs with localstack-logs-analysis.

Configuration reference

The following environment variables can be set in the env block of your MCP configuration:

Variable	Default	Description
LOCALSTACK_AUTH_TOKEN (required)	None	Your LocalStack Auth Token. Required for all MCP server tools.
LOCALSTACK_AZURE_IMAGE_NAME	localstack/localstack-azure:latest	Docker image that start launches for service: azure.
LOCALSTACK_AZURE_PORT	LOCALSTACK_PORT, then 4566	Gateway port of the Azure emulator the Azure tool talks to.
LOCALSTACK_AZURE_ENDPOINT	https://azure.localhost.localstack.cloud:<port>	ARM endpoint override: an https URL with no path. Only local names are accepted (localhost.localstack.cloud or a subdomain, localhost, 127.0.0.1, ::1).
LOCALSTACK_VOLUME_DIR	Per-OS cache directory	Host directory mounted at /var/lib/localstack. The Azure emulator needs a host directory here to deploy Function Apps and Web Apps.
LOCALSTACK_AZ_WORKDIR	The server’s working directory	Directory that the Azure tool’s file arguments must stay inside; also az’s working directory.
LOCALSTACK_AZ_PATH	PATH lookup	Explicit Azure CLI launcher (az, az.cmd) or its Python.
LOCALSTACK_AZ_BICEP_PATH	Auto-detect	Explicit Bicep binary. Otherwise ~/.localstack/azure/bin, then PATH.
LOCALSTACK_AZ_BICEP_ENV	None	Comma-separated server environment variables a .bicepparam file may read with readEnvironmentVariable().
LOCALSTACK_AZ_TIMEOUT_SECONDS	300	Per-command timeout of the Azure tool (5–3600).
LOCALSTACK_AZ_DENYLIST_FILE	None	A file of extra az command prefixes the tool refuses, one per line.
LOCALSTACK_AZ_RUNNER	host	worker (experimental) keeps warm Azure CLI processes, which makes each call faster.
MCP_ANALYTICS_DISABLED	0	Set to 1 to disable MCP analytics.

Emulator settings in the env block, such as LS_AZURE_PORTAL or MSSQL_ACCEPT_EULA, are forwarded to the container when localstack-management starts it. For example, to enable the Azure Portal Emulator and accept the SQL Server EULA:

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

Troubleshooting

The Azure tool can’t find az, an extension, or Bicep

Symptoms: A localstack-azure-client call fails because az is missing, or with a failure class such as extension or bicep-missing.

Solutions:

• Install the Azure CLI (2.85 or later) and make sure it is on the PATH of your MCP client, or point LOCALSTACK_AZ_PATH at it.
• Run npx -y @localstack/localstack-mcp-server install-azure-addons to install the extensions and Bicep.

A file argument is refused

Symptoms: A command fails with Path not allowed, saying that a file points outside the working directory.

Solutions:

• Move the file into the tool’s working directory, or set LOCALSTACK_AZ_WORKDIR to the folder that holds it.

A tool says it’s the wrong emulator for the job

Symptoms: A tool answers Wrong emulator for this tool.

Solutions:

• The tool works with the AWS emulator only. Use localstack-azure-client for the Azure emulator, or analysisType: logs with localstack-logs-analysis.

Tools return “Auth Token Required”

Symptoms: Any tool call fails with an “Auth Token Required” error.

Solutions:

• Confirm your LOCALSTACK_AUTH_TOKEN is set in the env block of your MCP configuration.
• Ensure there are no extra spaces or quotes around the token value in your configuration file.