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 s

... View full README on GitHub