localstack-mcp-server

重要

LocalStack MCP 服务目前作为实验性公开预览版提供。如有问题、遇到故障或有反馈，请使用 LocalStack Community Slack 或提交 GitHub Issue

LocalStack 可在本机模拟云环境，让软件团队和 AI Agent 能比在云端更快、更安全地验证安全性、质量和可靠性。此 Model Context Protocol（MCP）服务可让任何 MCP 客户端（Cursor、Claude、VS Code 等）通过自然语言启动 LocalStack、部署基础设施并调试本地云环境。

快速开始

使用交互式向导在 MCP 客户端中设置服务：

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

向导会检测已安装的客户端，询问你希望如何运行服务，并为你写入配置。你需要一个 LocalStack Auth Token；向导会从环境中读取 LOCALSTACK_AUTH_TOKEN，或提示你输入。完整的选项、前置条件和手动设置方法，请参阅安装。

你可以向 Agent 提出什么请求

配置好服务后，即可通过 Agent 使用自然语言与 LocalStack 交互：

• “启动 LocalStack 并部署 ./infra 中的 Terraform 项目，然后告诉我创建了哪些资源。”
• “我的 Lambda 调用失败了。读取 LocalStack 日志，找出权限错误，并生成能修复这些错误的 IAM 策略。”
• “向 DynamoDB 注入 500ms 延迟，并确认我的重试逻辑仍能正常工作。”
• “搜索 LocalStack 文档，了解如何启用 S3 事件通知，并总结操作步骤。”
• “启动 LocalStack Azure 模拟器，创建一个资源组和存储帐户，并将 ./data/sample.csv 上传到新的 Blob 容器。”

工作原理

该服务可将兼容 MCP 的应用直接连接到本地 LocalStack 环境及其模拟的 AWS 服务，让助手无需自定义脚本或手动设置，即可安全地操作服务栈。

该服务无需自定义脚本，也无需手动管理 LocalStack。你的 Agent 可以：

• 启动、停止、重启和监控用于 AWS、Snowflake 和 Azure 的 LocalStack 模拟器，并使用内置身份验证。
• 自动检测配置并部署 CDK、Terraform 和 SAM 项目。
• 搜索 LocalStack 文档，查找指南、API 参考和配置详情。
• 解析日志、捕获错误，并根据违规情况自动生成 IAM 策略。
• 向 LocalStack 注入混沌故障和网络影响，以测试系统韧性。
• 通过 Cloud Pods 管理 LocalStack 状态快照，以支持开发工作流。
• 使用基于文件的工作流，通过 Export & Import State 在本地导出、导入、检查和重置 LocalStack 状态。
• 从市场安装、移除、列出和查找 LocalStack Extensions。
• 启动和管理 Ephemeral Instances，以支持远程 LocalStack 测试工作流。
• 使用 AWS Replicator 将外部 AWS 资源复制到 LocalStack，让 IaC 服务栈能够在本地解析共享依赖项。
• 通过 App Inspector 检查 LocalStack 应用流程，包括跟踪、跨度、事件、负载元数据和 IAM 策略评估。
• 使用现成的 MCP 提示词启动可重复的 LocalStack 工作流，包括基础设施验证和集成测试生成。

工具

该服务为你的 AI 提供专用工具，用于管理 LocalStack 环境：

说明

此 MCP 服务中的所有工具都需要 LOCALSTACK_AUTH_TOKEN。 | 工具名称 | 描述 | 主要功能 | | :-------------------------------------------------------------------------------- | :------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | localstack-management | 管理 AWS、Snowflake 和 Azure 堆栈的 LocalStack 运行时操作 | - 执行启动、停止、重启和状态检查
- 集成 LocalStack 身份验证令牌
- 注入自定义环境变量
- 验证实时状态并执行运行状况监控 | | localstack-deployer | 处理面向 AWS 环境的 LocalStack 基础设施部署 | - 自动运行 CDK、Terraform 和 SAM 工具，在本地部署基础设施
- 支持使用变量进行参数化部署
- 处理并呈现部署结果
- 需要在系统路径中安装 cdklocal、tflocal 或 samlocal | | localstack-logs-analysis | 分析 LocalStack for AWS 日志，协助排查问题并获取见解 | - 提供多种分析选项，包括摘要、错误、请求和原始数据
- 按特定服务和操作筛选
- 生成 API 调用指标和故障细分
- 智能归类错误并识别模式 | | localstack-iam-policy-analyzer | 处理 IAM 策略管理和违规修复 | - 设置 IAM 强制级别，包括 enforced、soft 和 disabled 模式
- 搜索日志中的权限相关违规
- 根据检测到的访问失败自动生成 IAM 策略
- 需要有效的 LocalStack Auth Token | | localstack-chaos-injector | 注入并管理混沌实验故障，用于系统韧性测试 | - 注入、添加、移除和清除服务故障规则
- 配置网络延迟效果
- 按服务、区域和操作全面指定故障目标
- 内置混沌实验工作流指南
- 需要有效的 LocalStack Auth Token | | localstack-cloud-pods | 管理远程 LocalStack Cloud Pods，支持开发工作流 | - 将当前状态保存为 Cloud Pod
- 即时加载之前保存的 Cloud Pods
- 从远程云存储中删除 Cloud Pods
- 用于托管的远程状态快照，而非本地导出／导入文件
- 需要有效的 LocalStack Auth Token | | localstack-state-management | 管理基于本地文件的 LocalStack 状态导出／导入工作流 | - 通过 LocalStack State REST API 将 LocalStack 状态导出到本地磁盘文件
- 从本地文件导入 LocalStack 状态
- 将当前 LocalStack 状态作为 JSON 元模型数据进行检查
- 重置所有状态或仅重置选定的服务
- 支持按服务粒度进行导出、重置和检查
- 用于本地磁盘工作流；远程云托管快照请使用 Cloud Pods
- 需要有效的 LocalStack Auth Token | | localstack-extensions | 安装、卸载、列出和发现 LocalStack Extensions | - 在运行中的容器内管理已安装的扩展（list、install、uninstall）
- 浏览 LocalStack Extensions 市场（available）
- 需要有效的 LocalStack Auth Token | | localstack-ephemeral-instances | 管理云托管的 LocalStack Ephemeral Instances | - 创建临时云托管的 LocalStack 实例并获取端点 URL
- 列出可用的临时实例、获取日志并删除实例
- 创建时支持设置生命周期、预加载扩展、预加载 Cloud Pod 和自定义环境变量
- 需要有效的 LocalStack Auth Token | | localstack-aws-client | 在 LocalStack for AWS 容器内运行 AWS CLI 命令 | - 在运行中的容器内通过 awslocal 执行命令
- 清理命令以阻止 Shell 命令串联
- 自动检测 LocalStack 覆盖范围错误并链接到文档 | | localstack-azure-client | 针对 LocalStack for Azure 模拟器运行 Azure CLI（az）命令 | - 使用安装在你机器上的 Azure CLI 及其自身配置文件运行，不会使用你的 Azure 登录信息
- 阻止 Shell 语法以及会更改配置文件、安装软件或无法结束的命令
- 使用你通过 az extension add 安装的扩展
- 需要 Azure CLI 和有效的 LocalStack Auth Token | | localstack-aws-replicator | 将外部 AWS 资源复制到正在运行的 LocalStack 实例 | - 使用资源类型和标识符或 ARN 启动单资源复制作业
- 启动批量复制作业，例如复制指定路径前缀下的 SSM 参数
- 按作业 ID 轮询作业状态并列出现有作业
- 列出正在运行的 Replicator 扩展支持的资源类型
- 从 MCP 服务环境读取源 AWS 凭据，并支持可选的目标账户或区域覆盖 | | localstack-app-inspector | 检查 LocalStack 应用程序跟踪、跨度、事件和 IAM 评估 | - 为正在运行的 LocalStack 实例启用或禁用 App Inspector
- 列出并检查跟踪，以了解 AWS 服务间调用流程
- 深入检查跨度、事件、负载元数据和 IAM 策略评估事件
- 按服务、区域、操作、资源、ARN、状态和时间范围筛选
- 需要有效的 LocalStack Auth Token，以及已连接的 LocalStack 许可证中包含 App Inspector 功能 | | localstack-docs | 通过 CrawlChat 搜索 LocalStack 文档 | - 通过公开的 CrawlChat 集合查询 LocalStack 文档
- 仅返回重点摘要片段及其来源链接
- 无需运行 LocalStack 即可解答覆盖范围、配置和设置方面的问题 | | localstack-snowflake-client | 通过 snow CLI 在 LocalStack Snowflake 模拟器上运行 SQL | - 从查询字符串或 .sql 文件执行 SELECT、DDL（CREATE/DROP）、DML（INSERT/UPDATE/DELETE）以及 SHOW/DESCRIBE 语句
- 运行查询前检查 Snowflake 连接
- 为每条查询设置可选的数据库、架构、仓库和角色上下文
- 需要 Snowflake CLI（snow）和有效的 LocalStack Auth Token |

提示词

提示词是由 MCP 客户端作为斜杠命令或快捷操作提供、由用户选择的工作流模板。它们会为多步骤 LocalStack 任务设定框架，让助手每次都遵循相同的阶段、证据要求和报告格式。

提示词名称	描述	参数
infrastructure-tester	将 IaC 项目部署到 LocalStack，使用实时 AWS 探测和 App Inspector 证据验证声明的资源，然后编写并运行确定性集成测试。	iac_path（必填）、iac_type、test_language、test_framework、mode、services_focus、user_focus

安装

使用向导设置（推荐）

安装 MCP 服务最快的方法是使用交互式设置向导：

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

向导会：

• 让你选择运行服务的方式（在你的计算机上使用 npx，或使用独立的 Docker 镜像），
• 检查前置条件（Node.js、Docker），并告知你如何解决缺少的依赖，
• 从环境中读取 LOCALSTACK_AUTH_TOKEN，或提示你输入，
• 让你传入额外的 LocalStack 配置（例如，DEBUG=1,PERSISTENCE=1），
• 检测已安装的 MCP 客户端（Cursor、Antigravity、Claude Code、Claude Desktop、VS Code、Codex、OpenCode、Amazon Q CLI），并为你选择的客户端写入相应配置。

也可以完全以非交互方式运行，例如用于 dotfiles 或脚本：

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

如需从客户端中移除此服务：

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

运行 npx -y @localstack/localstack-mcp-server init --help 查看所有选项。

前置条件

• 已安装并运行 Docker。MCP 服务通过 Docker API 直接管理 LocalStack 容器。
• 如果要部署 CDK、Terraform 或 SAM 项目，系统路径中需安装 cdklocal、tflocal 或 samlocal
• 如果要使用 Snowflake 工具，系统路径中需安装 Snowflake CLI（snow）
• 如果要使用 Azure 工具，系统路径中需安装 Azure CLI（az）（参见 docs/AZURE.md）
• 已配置为 LOCALSTACK_AUTH_TOKEN 的有效 LocalStack Auth Token（所有 MCP 工具均必需）
• 系统路径中已安装 Node.js v20 或更高版本

使用 npx 运行

将以下内容添加到 MCP 客户端的配置文件中（例如，~/.cursor/mcp.json）。此配置使用 npx 运行服务；如有需要，它会自动下载并安装软件包。服务通过你的 Docker 守护程序管理 LocalStack；工具使用的任何部署 CLI 都从主机的 PATH 中运行。

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

所有 LocalStack MCP 工具都需要设置 LOCALSTACK_AUTH_TOKEN。请按照官方文档获取 LocalStack Auth Token。

从源代码运行

如果你从源代码安装，请修改 command 和 args，使其指向本地构建：

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

使用 Docker 运行

localstack/localstack-mcp-server Docker 镜像包含 Terraform/tflocal、CDK/cdklocal、SAM/samlocal 和 Snowflake CLI。主机上唯一必需的依赖是 Docker。容器使用挂载的 Docker 套接字，在主机上以同级容器的形式运行 LocalStack；除非 LOCALSTACK_VOLUME_DIR 指向主机目录，否则状态会存储在名为 localstack-mcp 的 Docker 卷中。

如果你使用部署工具处理本地 Terraform、CDK 或 SAM 项目，请将这些项目路径绑定挂载到 MCP 容器中，并向工具传入容器内的路径。最简单的约定是将项目挂载到与主机上相同的绝对路径。

{
  "mcpServers": {
    "localstack": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/var/run/docker.sock:/var/run/docker.sock",
        "--add-host",
        "host.docker.internal:host-gateway",
        "--add-host",
        "s3.host.docker.internal:host-gateway",
        "--add-host",
        "snowflake.localhost.localstack.cloud:host-gateway",
        "-e",
        "LOCALSTACK_AUTH_TOKEN",
        "-e",
        "LOCALSTACK_HOSTNAME=host.docker.internal",
        "-v",
        "/Users/you/projects:/Users/you/projects",
        "localstack/localstack-mcp-server:latest"
      ],
      "env": { "LOCALSTACK_AUTH_TOKEN": "<YOUR_TOKEN>" }
    }
  }
}

有关运行命令、MCP 客户端配置、IaC 项目挂载、CDK 说明和故障排除，请参阅 docs/DOCKER.md。

LocalStack 配置

变量名	描述	默认值
LOCALSTACK_AUTH_TOKEN (必需)	MCP 服务使用的 LocalStack Auth Token	无
LOCALSTACK_HOSTNAME	工具调用的 LocalStack 网关主机名；在 Docker 中为 host.docker.internal。Azure 工具始终调用 azure.localhost.localstack.cloud（127.0.0.1），因此需要本地网关。	localhost
LOCALSTACK_PORT	工具调用的 LocalStack 网关端口。	4566
MAIN_CONTAINER_NAME	Docker 工具使用的显式 LocalStack 容器名称。未设置时，服务会自动检测标准 LocalStack 容器（如 localstack-main 和 localstack-aws），然后检测 LocalStack Docker 镜像。	自动检测
LOCALSTACK_IMAGE_NAME / IMAGE_NAME	start 操作启动 AWS 堆栈时使用的 Docker 镜像。两者同时设置时，LOCALSTACK_IMAGE_NAME 优先（注意：裸变量 IMAGE_NAME 是常见的 CI 变量）。	localstack/localstack-pro:latest
LOCALSTACK_VOLUME_DIR	挂载到 LocalStack 容器中 /var/lib/localstack 的主机目录。默认使用 LocalStack CLI 采用的同一操作系统专属缓存路径（状态会沿用）；在 Docker 中，默认为名为 localstack-mcp 的卷。	操作系统专属缓存目录
GATEWAY_LISTEN	覆盖 start 的网关端口绑定（逗号分隔的 [host]:port）。设置后，将跳过隐式的 443 绑定。	:4566,:443
DOCKER_HOST	所有容器操作使用的 Docker 守护进程端点（unix://、npipe://、tcp://）。	平台默认套接字
DOCKER_SOCK	挂载到 LocalStack 容器中的 Docker 套接字主机路径（用于 Lambda）。显式设置时会验证其是否存在。	/var/run/docker.sock
EXTERNAL_SERVICE_PORTS_START / _END	start 时为外部服务发布的主机端口范围（含边界）。会验证范围（1–65535，起始值 ≤ 结束值）。	4510 / 4560
MCP_ANALYTICS_DISABLED	设置为 1 时禁用 MCP 分析	0
APP_INSPECTOR	在 LocalStack 容器环境中设置为 1，以便在每次重启后默认启用 App Inspector。MCP 工具也可以在运行时通过 set-status 切换 App Inspector。	0
AWS_ACCESS_KEY_ID (AWS Replicator 工具必需)	AWS Replicator 用于读取外部 AWS 资源的源 AWS 访问密钥	无
AWS_SECRET_ACCESS_KEY (AWS Replicator 工具必需)	AWS Replicator 用于读取外部 AWS 资源的源 AWS 秘密访问密钥	无
AWS_DEFAULT_REGION (AWS Replicator 工具必需)	AWS Replicator 使用的源 AWS 区域	无
LOCALSTACK_AZURE_IMAGE_NAME	start 操作启动 Azure 堆栈时使用的 Docker 镜像（默认为 localstack/localstack-azure:latest）。	最新 Azure 镜像
LOCALSTACK_AZ_PATH	Azure 工具使用的 az 启动器或 Azure CLI 的 Python。	在 PATH 中查找
LOCALSTACK_AZ_CONFIG_DIR	Azure 工具专用的 Azure CLI 配置文件目录（默认为 ~/.localstack/azure/mcp-config-<port>）；不得与 ~/.azure 重叠。	~/.localstack/azure 下
LOCALSTACK_AZ_WORKDIR	Azure 工具运行 az 的目录；相对文件路径将基于此目录解析。	服务的工作目录
LOCALSTACK_AZ_TIMEOUT_SECONDS	单条 Azure CLI 命令的时间限制（5–3600）。	300
有关 Azure 工具如何运行 Azure CLI，请参阅 docs/AZURE.md。

迁移说明（无 CLI 生命周期管理）

自 v0.6.0 起，MCP 服务不再使用（也不再需要）localstack CLI。LocalStack 容器现在通过 Docker Engine API 直接创建。与通过 CLI 启动相比，行为有所不同：

• 启动时不会读取 ~/.localstack/*.env 配置配置文件和 DOCKER_FLAGS。请通过 localstack-management 启动操作的 envVars 参数传递配置，或在 MCP 服务的环境中设置带 LOCALSTACK_ 前缀的变量（LocalStack 原生支持将 LOCALSTACK_<NAME> 映射为 <NAME>）。
• 除 LOCALSTACK_*/PROVIDER_OVERRIDE_* 外，只有一组经过筛选的常见无前缀配置变量会从主机环境转发（DEBUG、LS_LOG、SERVICES、PERSISTENCE、EAGER_SERVICE_LOADING、ENFORCE_IAM、IAM_SOFT_MODE、EXTENSION_AUTO_INSTALL、APP_INSPECTOR、DNS_ADDRESS、MAIN_DOCKER_NETWORK，以及 LAMBDA_*/CFN_*/SNOWFLAKE_*/SF_* 系列）。
• 默认会发布 443 端口。如果本地有其他程序占用 443 端口，请设置 GATEWAY_LISTEN=:4566 以跳过该端口。
• 如果你之前使用过 lstk，请注意服务创建的容器名为 localstack-main（仍会检测并管理外部启动的 localstack-aws 容器；restart 会保留它们的名称、镜像和卷）。

对于 AWS Replicator 专用的源凭证，可以使用带 AWS_REPLICATOR_SOURCE_ 前缀的变量，而不是无前缀变量。不要混用带前缀和无前缀的源凭证组；设置任何 AWS_REPLICATOR_SOURCE_ 变量后，Replicator 工具只会从该组读取源配置。

贡献

本项目基于 XMCP 框架构建。你可以在 src/tools 目录中添加新文件来新增工具，并在 manifest.json 文件中为其编写文档。

欢迎在 GitHub 上提交拉取请求！开始之前：

• 安装 Git 和 Node.js
• 克隆仓库
• 使用 yarn 安装依赖
• 使用 yarn build 构建

MCP Server Tester

此仓库包含 MCP Server Tester，用于在直接模式和大模型宿主模式下验证工具。

• 运行直接 MCP 测试（确定性）：

  yarn test:mcp:direct
  

• 运行基于 Gemini 的 MCP 宿主评估：

  export GOOGLE_GENERATIVE_AI_API_KEY="<your-gemini-key>"
  export LOCALSTACK_AUTH_TOKEN="<your-localstack-auth-token>"
  yarn test:mcp:evals
  

• 打开最新的 MCP Server Tester HTML 报告：

  npx mcp-server-tester open
  

• 运行两者：

  yarn test:mcp
  

说明：

• 默认情况下，MCP 测试会针对具备生命周期管理功能的本地服务命令 node dist/cli.js 运行。
• 所有 MCP 工具使用和测试套件都需要 LOCALSTACK_AUTH_TOKEN。
• 你可以使用以下变量覆盖目标命令：
  • MCP_TEST_COMMAND
  • MCP_TEST_ARGS（以空格分隔的参数）

许可证

Apache License 2.0