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).

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):

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