io.github.giovanemartins/localstack

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:

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

SQS

SNS

EventBridge

Kinesis

DynamoDB

Lambda

Secrets Manager

SSM Parameter Store

SES

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