localstack

LocalStack MCP 服务

此 MCP 服务将 LocalStack 管理的 AWS 服务作为 AI Agent 工具提供，使大模型和 AI Agent 能够在开发和测试期间与本地 AWS 基础设施交互。

安装

此服务已发布到 npm 和 MCP Registry。无需本地构建。

npm install -g @giovane.martins/localstack

也可以通过 npx 直接运行（无需安装）：

npx @giovane.martins/localstack

要求

• Node.js 20+
• Docker（用于 LocalStack）

本地开发

# 1. Start LocalStack
docker compose up -d

# 2. Install dependencies
pnpm install

# 3. Build
pnpm run build

# 4. Run
pnpm start

配置

所有配置均通过环境变量进行：

变量	默认值	描述
LOCALSTACK_ENDPOINT	http://localhost:4566	LocalStack 基础 URL
AWS_REGION	us-east-1	AWS 区域
AWS_ACCESS_KEY_ID	test	LocalStack 的虚假凭证
AWS_SECRET_ACCESS_KEY	test	LocalStack 的虚假凭证

运行测试

需要 LocalStack 正在运行（docker compose up -d）。

pnpm test

MCP 客户端配置

使用已发布的 npm 包（推荐）

将以下内容添加到 MCP 客户端配置中（例如 ~/.config/claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "localstack": {
      "command": "npx",
      "args": ["-y", "@giovane.martins/localstack"],
      "env": {
        "LOCALSTACK_ENDPOINT": "http://localhost:4566",
        "AWS_REGION": "us-east-1",
        "AWS_ACCESS_KEY_ID": "test",
        "AWS_SECRET_ACCESS_KEY": "test"
      }
    }
  }
}

使用本地构建

{
  "mcpServers": {
    "localstack": {
      "command": "node",
      "args": ["/path/to/mcp-servers/localstack/dist/index.js"],
      "env": {
        "LOCALSTACK_ENDPOINT": "http://localhost:4566",
        "AWS_REGION": "us-east-1",
        "AWS_ACCESS_KEY_ID": "test",
        "AWS_SECRET_ACCESS_KEY": "test"
      }
    }
  }
}

在开发时使用 tsx（无需构建）

{
  "mcpServers": {
    "localstack": {
      "command": "npx",
      "args": ["tsx", "/path/to/mcp-servers/localstack/src/index.ts"],
      "env": {
        "LOCALSTACK_ENDPOINT": "http://localhost:4566",
        "AWS_REGION": "us-east-1",
        "AWS_ACCESS_KEY_ID": "test",
        "AWS_SECRET_ACCESS_KEY": "test"
      }
    }
  }
}

---

可用工具

S3

工具	描述
s3_list_buckets	列出所有 S3 存储桶
s3_create_bucket	创建存储桶
s3_delete_bucket	删除存储桶
s3_put_object	上传对象（文本/JSON 内容）
s3_get_object	将对象下载为文本
s3_delete_object	删除对象
s3_list_objects	列出对象，可选按前缀筛选

SQS

工具	描述
sqs_list_queues	列出所有队列
sqs_create_queue	创建标准队列或 FIFO 队列
sqs_delete_queue	删除队列
sqs_send_message	发送消息
sqs_receive_messages	接收最多 10 条消息（支持长轮询）
sqs_delete_message	根据收据句柄删除消息
sqs_purge_queue	清空队列中的所有消息

SNS

工具	描述
sns_list_topics	列出所有主题
sns_create_topic	创建标准主题或 FIFO 主题
sns_delete_topic	删除主题
sns_subscribe	将终端节点订阅到主题
sns_unsubscribe	取消订阅主题
sns_list_subscriptions_by_topic	列出主题的所有订阅
sns_publish	向主题发布消息

EventBridge

工具	描述
eventbridge_list_buses	列出所有事件总线
eventbridge_create_bus	创建自定义事件总线
eventbridge_delete_bus	删除自定义事件总线
eventbridge_list_rules	列出总线上的规则
eventbridge_put_rule	创建或更新规则（事件模式或计划）
eventbridge_delete_rule	删除规则
eventbridge_describe_rule	描述规则
eventbridge_enable_rule	启用规则
eventbridge_disable_rule	禁用规则
eventbridge_put_targets	添加或更新规则目标
eventbridge_list_targets	列出规则的目标
eventbridge_remove_targets	从规则中移除目标
eventbridge_put_events	向总线发送自定义事件（最多 10 个）

Kinesis

工具	描述
kinesis_list_streams	列出所有流
kinesis_create_stream	创建流
kinesis_delete_stream	删除流
kinesis_describe_stream	描述流（状态、分片）
kinesis_put_record	写入一条记录
kinesis_put_records	写入多条记录（最多 500 条）
kinesis_get_records	从分片获取记录

DynamoDB

工具	描述
dynamodb_list_tables	列出所有表
dynamodb_create_table	创建表（分区键 + 可选的排序键）
dynamodb_delete_table	删除表
dynamodb_describe_table	描述表
dynamodb_put_item	写入（创建或替换）项目
dynamodb_get_item	根据键获取项目
dynamodb_delete_item	根据键删除项目
dynamodb_scan	扫描所有项目（可选筛选表达式）
dynamodb_query	根据键条件查询

Lambda

工具	描述
lambda_list_functions	列出所有函数
lambda_get_function	获取函数详情
lambda_create_function	根据 Base64 编码的 ZIP 创建函数
lambda_delete_function	删除函数
lambda_invoke	调用函数并返回其响应和日志

Secrets Manager

工具	描述
secretsmanager_list_secrets	列出所有密钥
secretsmanager_create_secret	创建新密钥
secretsmanager_get_secret	获取密钥的值
secretsmanager_update_secret	更新密钥的值
secretsmanager_describe_secret	描述密钥元数据
secretsmanager_delete_secret	删除密钥（可选强制删除）
secretsmanager_restore_secret	恢复之前删除的密钥

SSM Parameter Store

工具	描述
ssm_get_parameter	按名称获取参数
ssm_put_parameter	创建或更新参数
ssm_delete_parameter	删除参数
ssm_delete_parameters	批量删除最多 10 个参数
ssm_get_parameters_by_path	获取指定路径前缀下的所有参数
ssm_describe_parameters	列出并描述参数

SES

工具	描述
ses_list_identities	列出所有已验证身份
ses_verify_email_identity	验证电子邮件地址
ses_get_identity_verification_attributes	获取身份的验证状态
ses_delete_identity	删除身份
ses_send_email	发送电子邮件（纯文本和/或 HTML）

---

使用场景

• 开发环境初始化 — 根据规范一次性创建 S3 存储桶、SQS 队列、DynamoDB 表和 SSM 参数
• 测试数据填充 — 在运行集成测试前向 DynamoDB 或 S3 填充数据
• 事件驱动调试 — 向 EventBridge/SNS/Kinesis 发布消息，并在不离开 IDE 的情况下检查下游影响
• 密钥/配置管理 — 在本地调试会话期间读取和更新 Secrets Manager / SSM 中的值
• Lambda 冒烟测试 — 调用 Lambda 函数、捕获响应和日志，并快速迭代
• 队列清空/检查 — 无需运行消费者即可接收并检查 SQS 消息

---

项目结构

localstack/
├── docker-compose.yml      # LocalStack container
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── src/
│   ├── index.ts            # MCP server entry point
│   ├── config.ts           # Environment config
│   ├── tools/              # One file per AWS service
│   │   ├── s3.ts
│   │   ├── sqs.ts
│   │   ├── sns.ts
│   │   ├── eventbridge.ts
│   │   ├── kinesis.ts
│   │   ├── dynamodb.ts
│   │   ├── lambda.ts
│   │   ├── secretsmanager.ts
│   │   ├── ssm.ts
│   │   └── ses.ts
│   └── utils/
│       ├── client.ts       # Shared AWS client factory (LocalStack endpoint)
│       └── errors.ts       # Standardised MCP error formatting
└── tests/                  # Integration tests (real LocalStack)
    ├── s3.test.ts
    ├── sqs.test.ts
    ├── sns.test.ts
    ├── eventbridge.test.ts
    ├── kinesis.test.ts
    ├── dynamodb.test.ts
    ├── lambda.test.ts
    ├── secretsmanager.test.ts
    ├── ssm.test.ts
    └── ses.test.ts