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.
npm install -g @giovane.martins/localstack
Or run directly with npx (no install required):
npx @giovane.martins/localstack
Requirements
- Node.js 20+
- Docker (for LocalStack)
Local Development
# 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).
MCP Client Configuration
Using the published npm package (recommended)
Add to your MCP client config (e.g. ~/.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"
}
}
}
}
Using a local build
{
"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)
{
"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
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