MCP LocalStack Server

A Model Context Protocol (MCP) server that provides conversational access to LocalStack AWS services. Build, test, and debug cloud infrastructure through natural language without touching real AWS resources.

Features

• S3 Operations: Create buckets, upload/download objects, list contents
• DynamoDB: Create tables, put/get/scan items, manage data
• Lambda: Create functions, invoke them, retrieve logs
• SQS: Create queues, send/receive messages, manage queue attributes
• Zero AWS Costs: All operations run locally through LocalStack
• Natural Language Interface: Ask Claude to manage your infrastructure conversationally

Prerequisites

• Node.js >= 18.0.0
• LocalStack running locally
• Claude Desktop or any MCP-compatible client

Installation

1. Install LocalStack

# Using Docker (recommended)
docker run -d --name localstack -p 4566:4566 localstack/localstack

# Or install via pip
pip install localstack
localstack start

2. Install MCP LocalStack Server

git clone <your-repo-url>
cd mcp-localstack-server
npm install
npm run build

3. Configure Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "localstack": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-localstack-server/dist/index.js"],
      "env": {
        "LOCALSTACK_ENDPOINT": "http://localhost:4566",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

Usage Examples

Once configured, you can interact with LocalStack through natural language in Claude:

S3 Operations

You: Create an S3 bucket called my-test-bucket
You: Upload a file to my-test-bucket with key data.json containing {"test": "value"}
You: List all objects in my-test-bucket
You: Get the contents of data.json from my-test-bucket

DynamoDB Operations

You: Create a DynamoDB table called Users with id as the hash key
You: Put an item in Users table: {"id": "user123", "name": "John", "email": "john@example.com"}
You: Get item from Users table with id user123
You: Scan the entire Users table

Lambda Operations

You: Create a Lambda function called hello-world using Python 3.9
You: Invoke the hello-world function with payload {"name": "Alice"}
You: Get the logs from hello-world function

SQS Operations

You: Create an SQS queue called my-queue
You: Send a message to my-queue with body "Hello from SQS"
You: Receive messages from my-queue
You: Get the attributes of my-queue

Available Tools

S3

• s3_create_bucket - Create a new bucket
• s3_list_buckets - List all buckets
• s3_upload_object - Upload an object
• s3_list_objects - List objects in a bucket
• s3_get_object - Get object contents
• s3_delete_object - Delete an object

DynamoDB

• dynamodb_create_table - Create a table
• dynamodb_list_tables - List all tables
• dynamodb_put_item - Insert an item
• dynamodb_get_item - Retrieve an item
• dynamodb_scan - Scan table
• dynamodb_delete_item - Delete an item
• dynamodb_delete_table - Delete a table

Lambda

• lambda_create_function - Create a function
• lambda_invoke - Invoke a function
• lambda_list_functions - List all functions
• lambda_get_function - Get function details
• lambda_delete_function - Delete a function
• lambda_get_logs - Retrieve function logs

SQS

• sqs_create_queue - Create a queue
• sqs_list_queues - List all queues
• sqs_send_message - Send a message
• sqs_receive_messages - Receive messages
• sqs_delete_message - Delete a message
• sqs_get_queue_url - Get queue URL
• sqs_delete_queue - Delete a queue
• sqs_get_queue_attributes - Get queue attributes

Environment Variables

• LOCALSTACK_ENDPOINT - LocalStack endpoint (default: http://localhost:4566)
• AWS_REGION - AWS region (default: us-east-1)
• AWS_ACCESS_KEY_ID - Access key (default: test)
• AWS_SECRET_ACCESS_KEY - Secret key (default: test)

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch

Troubleshooting

LocalStack not responding

Ensure LocalStack is running:

docker ps | grep localstack

If not running, start it:

docker start localstack

Connection refused errors

Verify LocalStack endpoint:

curl http://localhost:4566/_localstack/health

Tools not appearing in Claude

1. Restart Claude Desktop completely
2. Check config file path is correct
3. Verify absolute path to dist/index.js
4. Check Claude Desktop logs for errors

Contributing

Contributions welcome! This project fills a gap in the MCP ecosystem and benefits from community input.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT License - see LICENSE file for details

Why This Matters

LocalStack is a powerful tool for AWS development, but it requires knowledge of AWS CLIs, SDKs, and APIs. This MCP server makes cloud development accessible through conversation—ask Claude to manage your infrastructure instead of writing boto3 scripts or memorizing AWS CLI commands.

Perfect for:

• Learning AWS services without cost
• Testing infrastructure changes safely
• Rapid prototyping of cloud architectures
• Teaching cloud concepts interactively
• CI/CD pipeline development

Acknowledgments

Built on:

• Model Context Protocol by Anthropic
• LocalStack for local AWS simulation
• AWS SDK for JavaScript v3