io.github.giovanemartins/localstack

Name: io.github.giovanemartins/localstack
Rating: 0.1 (1 reviews)
Author: giovanemartins

编码与调试

by giovanemartins

MCP server for LocalStack AWS services, enabling AI agents to interact with local AWS infra.

1GitHub

什么是 io.github.giovanemartins/localstack？

MCP server for LocalStack AWS services, enabling AI agents to interact with local AWS infra.

README

LocalStack MCP Server

MCP server that exposes LocalStack-managed AWS services as AI-agent tools, enabling LLMs and AI agents to interact with local AWS infrastructure during development and testing.

Installation

The server is published to npm and the MCP Registry. No local build needed.

bash

npm install -g @giovane.martins/localstack

Or run directly with npx (no install required):

bash

npx @giovane.martins/localstack

Requirements

Node.js 20+
Docker (for LocalStack)

Local Development

bash

# 1. Start LocalStack
docker compose up -d

# 2. Install dependencies
pnpm install

# 3. Build
pnpm run build

# 4. Run
pnpm start

Configuration

All configuration is via environment variables:

Variable	Default	Description
`LOCALSTACK_ENDPOINT`	`http://localhost:4566`	LocalStack base URL
`AWS_REGION`	`us-east-1`	AWS region
`AWS_ACCESS_KEY_ID`	`test`	Fake credentials for LocalStack
`AWS_SECRET_ACCESS_KEY`	`test`	Fake credentials for LocalStack

Running Tests

Requires LocalStack running (docker compose up -d).

bash

pnpm test

MCP Client Configuration

Using the published npm package (recommended)

Add to your MCP client config (e.g. ~/.config/claude/claude_desktop_config.json):

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"
      }
    }
  }
}

Using a local build

json

{
  "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"
      }
    }
  }
}

Using `tsx` for development (no build step)

json

{
  "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"
      }
    }
  }
}

Available Tools

S3

Tool	Description
`s3_list_buckets`	List all S3 buckets
`s3_create_bucket`	Create a bucket
`s3_delete_bucket`	Delete a bucket
`s3_put_object`	Upload an object (text/JSON content)
`s3_get_object`	Download an object as text
`s3_delete_object`	Delete an object
`s3_list_objects`	List objects with optional prefix filter

SQS

Tool	Description
`sqs_list_queues`	List all queues
`sqs_create_queue`	Create a standard or FIFO queue
`sqs_delete_queue`	Delete a queue
`sqs_send_message`	Send a message
`sqs_receive_messages`	Receive up to 10 messages (with long-polling support)
`sqs_delete_message`	Delete a message by receipt handle
`sqs_purge_queue`	Purge all messages from a queue

SNS

Tool	Description
`sns_list_topics`	List all topics
`sns_create_topic`	Create a standard or FIFO topic
`sns_delete_topic`	Delete a topic
`sns_subscribe`	Subscribe an endpoint to a topic
`sns_unsubscribe`	Unsubscribe from a topic
`sns_list_subscriptions_by_topic`	List all subscriptions for a topic
`sns_publish`	Publish a message to a topic

EventBridge

Tool	Description
`eventbridge_list_buses`	List all event buses
`eventbridge_create_bus`	Create a custom event bus
`eventbridge_delete_bus`	Delete a custom event bus
`eventbridge_list_rules`	List rules on a bus
`eventbridge_put_rule`	Create or update a rule (event pattern or schedule)
`eventbridge_delete_rule`	Delete a rule
`eventbridge_describe_rule`	Describe a rule
`eventbridge_enable_rule`	Enable a rule
`eventbridge_disable_rule`	Disable a rule
`eventbridge_put_targets`	Add or update rule targets
`eventbridge_list_targets`	List targets for a rule
`eventbridge_remove_targets`	Remove targets from a rule
`eventbridge_put_events`	Send custom events to a bus (max 10)

Kinesis

Tool	Description
`kinesis_list_streams`	List all streams
`kinesis_create_stream`	Create a stream
`kinesis_delete_stream`	Delete a stream
`kinesis_describe_stream`	Describe a stream (status, shards)
`kinesis_put_record`	Put a single record
`kinesis_put_records`	Put multiple records (max 500)
`kinesis_get_records`	Get records from a shard

DynamoDB

Tool	Description
`dynamodb_list_tables`	List all tables
`dynamodb_create_table`	Create a table (partition key + optional sort key)
`dynamodb_delete_table`	Delete a table
`dynamodb_describe_table`	Describe a table
`dynamodb_put_item`	Put (create or replace) an item
`dynamodb_get_item`	Get an item by key
`dynamodb_delete_item`	Delete an item by key
`dynamodb_scan`	Scan all items (with optional filter expression)
`dynamodb_query`	Query by key condition

Lambda

Tool	Description
`lambda_list_functions`	List all functions
`lambda_get_function`	Get function details
`lambda_create_function`	Create a function from a base64-encoded ZIP
`lambda_delete_function`	Delete a function
`lambda_invoke`	Invoke a function and return its response + logs

Secrets Manager

Tool	Description
`secretsmanager_list_secrets`	List all secrets
`secretsmanager_create_secret`	Create a new secret
`secretsmanager_get_secret`	Get the value of a secret
`secretsmanager_update_secret`	Update the value of a secret
`secretsmanager_describe_secret`	Describe secret metadata
`secretsmanager_delete_secret`	Delete a secret (with optional force delete)
`secretsmanager_restore_secret`	Restore a previously deleted secret

SSM Parameter Store

Tool	Description
`ssm_get_parameter`	Get a parameter by name
`ssm_put_parameter`	Create or update a parameter
`ssm_delete_parameter`	Delete a parameter
`ssm_delete_parameters`	Delete up to 10 parameters in batch
`ssm_get_parameters_by_path`	Get all parameters under a path prefix
`ssm_describe_parameters`	List and describe parameters

SES

Tool	Description
`ses_list_identities`	List all verified identities
`ses_verify_email_identity`	Verify an email address
`ses_get_identity_verification_attributes`	Get verification status for identities
`ses_delete_identity`	Delete an identity
`ses_send_email`	Send an email (plain text and/or HTML)

Use Cases

Dev environment bootstrap — create S3 buckets, SQS queues, DynamoDB tables, and SSM parameters in one shot from a spec
Test data seeding — populate DynamoDB or S3 before running integration tests
Event-driven debugging — publish to EventBridge/SNS/Kinesis and inspect downstream effects without leaving the IDE
Secret/config management — read and update Secrets Manager / SSM values during local debug sessions
Lambda smoke testing — invoke Lambda functions, capture responses and logs, iterate quickly
Queue drain / inspect — receive and inspect SQS messages without a consumer running

Project Structure

code

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

常见问题