Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions .github/actions/host-tools/action.yml
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
name: Host tools
description: >-
Puts the Docker image's tools on the PATH for jobs that run the MCP server on the host:
always Terraform and uv (from the Dockerfile's host-tools stage) and lstk (docker/tools/npm), and
always Terraform, uv and the AWS CLI (from the Dockerfile's host-tools stage) and lstk
(docker/tools/npm), and
optionally the Snowflake CLI from docker/tools/snowflake. Versions change only in those files.
inputs:
snowflake:
Expand All @@ -11,11 +12,13 @@ inputs:
runs:
using: composite
steps:
- name: Copy Terraform and uv out of the Dockerfile
# The AWS CLI comes first on the PATH, ahead of the one the runner image ships.
- name: Copy Terraform, uv and the AWS CLI out of the Dockerfile
shell: bash
run: |
docker build --target host-tools --output "type=local,dest=$RUNNER_TEMP/host-tools" .
echo "$RUNNER_TEMP/host-tools" >> "$GITHUB_PATH"
echo "$RUNNER_TEMP/host-tools/aws-cli/bin" >> "$GITHUB_PATH"

- name: Install lstk
shell: bash
Expand Down
7 changes: 5 additions & 2 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
Expand Up @@ -59,13 +59,16 @@ updates:
- minor
- patch

# FROM lines in the Dockerfile: node and hashicorp/terraform.
# FROM lines in the Dockerfile: node, hashicorp/terraform, astral-sh/uv and amazon/aws-cli.
# Releases wait 30 days: amazon/aws-cli ships almost daily, and each bump makes users pull its
# layer again. The docker ecosystem has no per-SemVer cooldown and one entry cannot set one per
# image, so the other images wait as long. Security updates are never delayed.
- package-ecosystem: docker
directory: /
schedule:
interval: weekly
cooldown:
default-days: 7
default-days: 30
open-pull-requests-limit: 5
groups:
docker-minor-patch:
Expand Down
27 changes: 22 additions & 5 deletions Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,13 @@

# Every tool version in this image comes from a file Dependabot updates (.github/dependabot.yml):
# node, terraform FROM lines below (docker)
# aws-cli (v2) FROM line below (docker)
# aws-cdk, lstk docker/tools/npm/package-lock.json (npm)
# uv FROM line below (docker)
# aws-sam-cli docker/tools/sam/uv.lock (uv)
# snowflake-cli docker/tools/snowflake/uv.lock (uv)
# dockerode & co. yarn.lock (npm, same lock as CI)
# The host-tools stage hands the same terraform and uv binaries to CI jobs that run on the host.
# The host-tools stage hands the same terraform, uv and AWS CLI to CI jobs that run on the host.
# Debian packages (python3, git, curl) come with the node image's bookworm base.
# Both node FROM lines must stay identical, and their major must match `node-version` in the
# workflows; src/core/dependency-pins.test.ts checks this.
Expand All @@ -25,14 +26,25 @@ RUN yarn build
# Terraform's official image ships a static binary, so it runs on Debian as well.
FROM hashicorp/terraform:1.17.2 AS terraform

# AWS's official image of the AWS CLI v2. Its installation under /usr/local/aws-cli is
# self-contained (frozen Python, built for an old glibc), so it runs on Debian as well.
# Trimmed here, before the COPYs, so the 35 MB never reach a layer: the per-service examples
# only feed `aws <cmd> help` (which still needs the top-level global_*.rst), and aws_completer
# only shell Tab completion. The models stay uncompressed: this CLI cannot read .json.gz.
FROM amazon/aws-cli:2.39.3 AS awscli
RUN cd /usr/local/aws-cli/v2/current \
&& find dist/awscli/examples -mindepth 1 -maxdepth 1 -type d -exec rm -rf {} + \
&& rm -f dist/aws_completer bin/aws_completer

# uv installs the Python CLIs below; it is mounted at build time and not part of the image.
FROM ghcr.io/astral-sh/uv:0.13.9 AS uv

# Terraform and uv for CI jobs that run on the host, at the image's versions
# Terraform, uv and the AWS CLI for CI jobs that run on the host, at the image's versions
# (.github/actions/host-tools): docker build --target host-tools --output type=local,dest=DIR .
FROM scratch AS host-tools
COPY --from=terraform /bin/terraform /
COPY --from=uv /uv /uvx /
COPY --from=awscli /usr/local/aws-cli/v2/current/ /aws-cli/

FROM node:22.23.5-bookworm-slim AS runtime
ENV DEBIAN_FRONTEND=noninteractive \
Expand All @@ -41,17 +53,22 @@ ENV DEBIAN_FRONTEND=noninteractive \
UV_LINK_MODE=copy

# python3 and python3-pip also serve `sam build` for Python functions (Debian's Python 3.11;
# other Python runtimes need `sam build --use-container`).
# other Python runtimes need `sam build --use-container`). mandoc renders `aws … help`.
RUN set -eux; \
apt-get update; \
apt-get install -y --no-install-recommends ca-certificates curl unzip git \
python3 python3-pip python3-venv; \
python3 python3-pip python3-venv mandoc; \
apt-get clean; \
rm -rf /var/lib/apt/lists/*

COPY --from=terraform /bin/terraform /usr/local/bin/terraform
RUN terraform version

# `lstk aws` runs this CLI for the AWS client tool and the deployer's CloudFormation actions.
COPY --from=awscli /usr/local/aws-cli/v2/current/ /usr/local/aws-cli/
RUN ln -s /usr/local/aws-cli/bin/aws /usr/local/bin/aws \
&& aws --version

# SAM CLI and Snowflake CLI each get their own venv from their own uv project: they pin
# conflicting `rich` versions, so one environment cannot hold both. uv verifies every package
# against the hashes in uv.lock, and --no-build refuses anything that would need a compiler.
Expand All @@ -75,7 +92,7 @@ RUN --mount=from=uv,source=/uv,target=/bin/uv \
&& ln -s /opt/snowflake-cli/bin/snow /usr/local/bin/snow \
&& snow --version

# lstk wraps terraform, cdk, and sam for the deployer tool. aws-cdk >= 2.1138 honors the
# lstk wraps the AWS CLI, terraform, cdk, and sam. aws-cdk >= 2.1138 honors the
# CDK_S3_FORCE_PATH_STYLE that lstk sets, so S3 assets reach host.docker.internal path-style.
COPY docker/tools/npm/package.json docker/tools/npm/package-lock.json /opt/image-tools/npm/
RUN npm ci --prefix /opt/image-tools/npm --omit=dev --ignore-scripts --no-audit --no-fund \
Expand Down
11 changes: 6 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ This server provides your AI with dedicated tools for managing your LocalStack e
| [`localstack-state-management`](./src/tools/localstack-state-management.ts) | Manages local file-based LocalStack state export/import workflows | - Export LocalStack state to a local file on disk through the LocalStack State REST API<br/>- Import LocalStack state from a local file<br/>- Inspect current LocalStack state as JSON metamodel data<br/>- Reset all state or only selected services<br/>- Supports service-level granularity for export, reset, and inspect<br/>- Use this for local disk workflows; use Cloud Pods for remote cloud-backed snapshots<br/>- Requires a valid LocalStack Auth Token |
| [`localstack-extensions`](./src/tools/localstack-extensions.ts) | Installs, uninstalls, lists, and discovers LocalStack Extensions | - Manage installed extensions (`list`, `install`, `uninstall`) inside the running container<br/>- Browse the LocalStack Extensions marketplace (`available`)<br/>- Requires a valid LocalStack Auth Token |
| [`localstack-ephemeral-instances`](./src/tools/localstack-ephemeral-instances.ts) | Manages cloud-hosted LocalStack Ephemeral Instances | - Create temporary cloud-hosted LocalStack instances and get an endpoint URL<br/>- List available ephemeral instances, fetch logs, and delete instances<br/>- Supports lifetime, extension preload, Cloud Pod preload, and custom env vars on create<br/>- Requires a valid LocalStack Auth Token |
| [`localstack-aws-client`](./src/tools/localstack-aws-client.ts) | Runs AWS CLI commands inside the LocalStack for AWS container | - Executes commands via `awslocal` inside the running container<br/>- Sanitizes commands to block shell chaining<br/>- Auto-detects LocalStack coverage errors and links to docs |
| [`localstack-aws-client`](./src/tools/localstack-aws-client.ts) | Runs AWS CLI commands against LocalStack for AWS | - Executes commands with the official AWS CLI v2 through `lstk aws`, so it requires `lstk` and `aws` in your system path<br/>- Keeps every request on LocalStack: the CLI runs without your `~/.aws` and behind a local proxy that refuses other hosts<br/>- Reads and writes local files only inside `LOCALSTACK_AWS_WORKDIR`<br/>- Sanitizes commands to block shell chaining<br/>- Auto-detects LocalStack coverage errors and links to docs |
| [`localstack-azure-client`](./src/tools/localstack-azure-client.ts) | Runs Azure CLI (`az`) commands against the LocalStack for Azure emulator | - Runs the Azure CLI installed on your machine with its own profile, never your Azure login<br/>- Blocks shell syntax and commands that would change the profile, install software or never end<br/>- Uses the extensions you installed with `az extension add`<br/>- Requires the Azure CLI and a valid LocalStack Auth Token |
| [`localstack-aws-replicator`](./src/tools/localstack-aws-replicator.ts) | Replicates external AWS resources into a running LocalStack instance | - Start single-resource replication jobs with a resource type and identifier or ARN<br/>- Start batch replication jobs, such as SSM parameters under a path prefix<br/>- Poll job status by job ID and list existing jobs<br/>- List resource types supported by the running Replicator extension<br/>- Reads source AWS credentials from the MCP server environment and supports optional target account or region overrides |
| [`localstack-app-inspector`](./src/tools/localstack-app-inspector.ts) | Inspects LocalStack application traces, spans, events, and IAM evaluations | - Enable or disable App Inspector for the running LocalStack instance<br/>- List and inspect traces to understand AWS service-to-service flows<br/>- Drill into spans, events, payload metadata, and IAM policy evaluation events<br/>- Filter by service, region, operation, resource, ARN, status, and time range<br/>- Requires a valid LocalStack Auth Token and the App Inspector feature in the connected LocalStack license |
Expand Down Expand Up @@ -124,7 +124,7 @@ 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.
- [`lstk`](https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/) (`npm install -g @localstack/lstk`) plus the Terraform, AWS CDK (2.177.0 or newer), or AWS SAM (1.95.0 or newer) CLI in your system path if you want to deploy Terraform, CDK, or SAM projects
- [`lstk`](https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/) (`npm install -g @localstack/lstk`) and the [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) if you want to run AWS CLI commands or deploy CloudFormation stacks, plus the Terraform, AWS CDK (2.177.0 or newer), or AWS SAM (1.95.0 or newer) CLI in your system path if you want to deploy Terraform, CDK, or SAM projects
- Snowflake CLI (`snow`) installed in your system path if you want to use the Snowflake tool
- Azure CLI (`az`) installed in your system path if you want to use the Azure tool (see [docs/AZURE.md](./docs/AZURE.md))
- A [valid LocalStack Auth Token](https://docs.localstack.cloud/aws/getting-started/auth-token/) configured as `LOCALSTACK_AUTH_TOKEN` (**required for all MCP tools**)
Expand Down Expand Up @@ -170,7 +170,7 @@ If you installed from source, change `command` and `args` to point to your local

### Run with Docker

The `localstack/localstack-mcp-server` Docker image bundles `lstk` with Terraform, CDK, and SAM, 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.
The `localstack/localstack-mcp-server` Docker image bundles `lstk` with the AWS CLI v2, Terraform, CDK, and SAM, 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.

Expand Down Expand Up @@ -227,6 +227,7 @@ See **[docs/DOCKER.md](./docs/DOCKER.md)** for the run command, MCP client confi
| `LOCALSTACK_AZURE_IMAGE_NAME` | Docker image the `start` action launches for the Azure stack (default `localstack/localstack-azure:latest`). | Latest Azure image |
| `LOCALSTACK_AZ_PATH` | The `az` launcher, or the Azure CLI's Python, for the Azure tool. | Found on `PATH` |
| `LOCALSTACK_AZ_CONFIG_DIR` | The Azure tool's own Azure CLI profile directory (default `~/.localstack/azure/mcp-config-<port>`); it must not overlap your `~/.azure`. | Under `~/.localstack/azure` |
| `LOCALSTACK_AWS_WORKDIR` | The directory the AWS client tool runs the AWS CLI in. Local files a command reads or writes (`s3 cp`, `file://`, `--body`, an outfile) must be inside it. Unset in the Docker image, and when the server runs in `/` or your home directory: then only relative paths work, in a private temp directory. | The server's working directory |
| `LOCALSTACK_AZ_WORKDIR` | The directory the Azure tool runs `az` in; relative file paths resolve against it. | The server's working directory |
| `LOCALSTACK_AZ_TIMEOUT_SECONDS` | Time limit for one Azure CLI command (5–3600). | `300` |

Expand Down Expand Up @@ -267,14 +268,14 @@ This repository includes [MCP Server Tester](https://github.com/gleanwork/mcp-se
export LOCALSTACK_AUTH_TOKEN="<your-localstack-auth-token>"
yarn test:mcp:tools
```
The tests deploy a sample project, switch IAM enforcement to soft mode and save a Cloud Pod, so point them at an instance you don't need: set `LOCALSTACK_PORT` and `MAIN_CONTAINER_NAME` to use one other than the default on 4566. They need Docker, Terraform and [lstk](https://github.com/localstack/lstk) on the `PATH`.
The tests deploy a sample project, switch IAM enforcement to soft mode and save a Cloud Pod, so point them at an instance you don't need: set `LOCALSTACK_PORT` and `MAIN_CONTAINER_NAME` to use one other than the default on 4566. They need Docker, Terraform, the AWS CLI v2 and [lstk](https://github.com/localstack/lstk) on the `PATH`.
- Run MCP host evals through [OpenRouter](https://openrouter.ai) (default model `google/gemini-2.5-flash`; set `EVAL_MODEL` to any OpenRouter model ID to override it):
```bash
export OPENROUTER_API_KEY="<your-openrouter-key>"
export LOCALSTACK_AUTH_TOKEN="<your-localstack-auth-token>"
yarn test:mcp:evals
```
The evals check whether a model picks and combines the right tools for a goal; their prompts don't name the tools. They start, change and stop LocalStack on port 4566, so don't run them against an instance you're using. They need Docker, Terraform, [lstk](https://github.com/localstack/lstk) and the Snowflake CLI (`snow`) on the `PATH`, and the sample project's providers downloaded with `terraform -chdir=data/sample-terraform init`.
The evals check whether a model picks and combines the right tools for a goal; their prompts don't name the tools. They start, change and stop LocalStack on port 4566, so don't run them against an instance you're using. They need Docker, Terraform, the AWS CLI v2, [lstk](https://github.com/localstack/lstk) and the Snowflake CLI (`snow`) on the `PATH`, and the sample project's providers downloaded with `terraform -chdir=data/sample-terraform init`.
The [MCP evals workflow](./.github/workflows/mcp-evals.yml) runs them after every merge into `main` that changes the server, its tools or the evals, weekly and on demand; it needs the `OPENROUTER_API_KEY` repository secret.
- Open the latest MCP Server Tester HTML report:
```bash
Expand Down
12 changes: 12 additions & 0 deletions data/sample-cloudformation/template.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
AWSTemplateFormatVersion: "2010-09-09"
Description: Sample stack for the localstack-deployer create-stack and delete-stack actions.

Resources:
Queue:
Type: AWS::SQS::Queue
Properties:
QueueName: !Sub "${AWS::StackName}-queue"

Outputs:
QueueUrl:
Value: !Ref Queue
Loading