# 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](https://docs.localstack.cloud/getting-started/installation/) running locally
- [Claude Desktop](https://claude.ai/download) or any MCP-compatible client

## Installation

### 1. Install LocalStack

```bash
# 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

```bash
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`

```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

```bash
# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch
```

## Troubleshooting

### LocalStack not responding

Ensure LocalStack is running:
```bash
docker ps | grep localstack
```

If not running, start it:
```bash
docker start localstack
```

### Connection refused errors

Verify LocalStack endpoint:
```bash
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](https://modelcontextprotocol.io/) by Anthropic
- [LocalStack](https://localstack.cloud/) for local AWS simulation
- AWS SDK for JavaScript v3