# ☁️ AWS MCP Server

> **Read-only Model Context Protocol server for AWS resources — multi-region, caching, audit, and AI-ready.**

---

## 📋 Overview

This MCP server exposes **60+ read-only tools** across AWS services: identity, EC2, S3, IAM, Cost Explorer, CloudWatch, GuardDuty, CloudTrail, ELB, WAF, Route53, ECS, EKS, RDS, Lambda, and more.

| Flow | Description |
|------|-------------|
| 🔌 | MCP client connects to this server |
| 🛠️ | Server invokes AWS APIs (read-only) |
| 📤 | Returns resources, metrics, cost data to the AI agent |

---

## 🛠️ Tech Stack

| Layer | Technology | Purpose |
|-------|------------|---------|
| ☁️ **MCP Server** | TypeScript, AWS SDK v3 | Protocol handler, tool dispatch |
| 📦 **Runtime** | Node.js (v18+) | Execution |
| 🔐 **Auth** | AWS credentials (keys, profiles, SSO) | AWS API calls |

---

## 🗣️ Languages

| Language | Used In |
|----------|---------|
| **TypeScript** | MCP server, tools, CLI, libs |
| **JSON** | Config (`mcp-config.json`), MCP schema |

---

## 📁 Project Structure

```
├── src/
│   ├── index.ts          # MCP server entry, tool dispatch, resources, prompts
│   ├── load-env.ts       # Loads .env before other modules
│   ├── clients.ts        # Shared AWS clients (one per service)
│   ├── cli.ts            # Local CLI for testing tools
│   ├── integration.test.ts
│   └── lib/              # config, cache, retry, audit, rate-limit, webhook, etc.
├── docs/                 # TOOLS.md, IAM_PERMISSIONS.md, CONFIG.md, TROUBLESHOOTING.md
├── mcp-config.json.example   # Optional: webhook, rate limit, defaults (copy to mcp-config.json)
├── Dockerfile            # Container image for running the server
└── .env                  # AWS credentials (copy from .env.example)
```

---

## ⚡ Capabilities

| Feature | Description |
|---------|-------------|
| **Multi-region** | `region` parameter on EC2, VPCs, RDS, Lambda tools |
| **Pagination** | `max_results` on list_iam_users, list_s3_buckets, list_ecs_clusters, list_dynamodb_tables, list_cloudformation_stacks |
| **MCP resources** | Browse `aws://region/service/id` (identity, EC2, S3, cost, RDS, Lambda, GuardDuty) |
| **MCP prompts** | AI guidance for cost, security, and resource-list queries |
| **Caching** | Optional in-memory cache (TTL via `MCP_AWS_CACHE_TTL`) |
| **Retry** | Exponential backoff for throttled AWS calls |
| **Audit log** | Log tool invocations when `MCP_AWS_AUDIT_LOG=true` |
| **Dry-run** | Mock data when `MCP_AWS_DRY_RUN=true` (no AWS calls) |
| **LocalStack** | Set `AWS_ENDPOINT_URL=http://localhost:4566` |
| **Health check** | `aws_health_check` tool to verify credentials |
| **IAM policy** | `get_iam_policy_for_tools` generates least-privilege policy |
| **CLI** | `npm run cli -- get_aws_caller_identity` for local testing |
| **Config file** | `mcp-config.json` for webhook, rate limit, defaults |
| **estimate_cost** | Rough cost estimate for EC2, Lambda, RDS, S3 |
| **scan_secrets_risks** | Find Secrets Manager secrets needing attention |
| **Tag filter** | `tag_filter` on list_ec2_instances, list_rds_instances |
| **SSO / cross-account** | See [docs/SSO_AND_CROSS_ACCOUNT.md](docs/SSO_AND_CROSS_ACCOUNT.md) |

📖 **Documentation:** [TOOLS.md](docs/TOOLS.md) · [IAM_PERMISSIONS.md](docs/IAM_PERMISSIONS.md) · [CONFIG.md](docs/CONFIG.md) · [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)

---

## 🚀 Quick Start

```bash
# 1. Configure environment
cp .env.example .env   # Add AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION

# 2. Install and build
npm install
npm run build

# 3. Test locally (dry-run, no AWS calls)
MCP_AWS_DRY_RUN=true npm run cli -- get_aws_caller_identity
```

### MCP Client Configuration

```json
{
  "mcpServers": {
    "aws-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "AWS_ACCESS_KEY_ID": "YOUR_ACCESS_KEY",
        "AWS_SECRET_ACCESS_KEY": "YOUR_SECRET_KEY",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}
```

---

## 📦 Sharing with Your Team

### Option A: Git

1. Push to a private repo.
2. Team clones, runs `npm install && npm run build`.
3. Point MCP client at `dist/index.js` (absolute path).

### Option B: Package (.tgz)

```bash
npm pack   # Creates mcp-server-aws-1.0.0.tgz
npm install -g mcp-server-aws-1.0.0.tgz
```

Then configure MCP client with `"command": "mcp-server-aws"`.

### Option C: Docker

```bash
docker build -t mcp-server-aws .
docker run -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_REGION mcp-server-aws
```

---

## 🔧 Development

```bash
npm run dev        # Watch mode
npm run typecheck  # TypeScript check (no emit)
npm run cli -- <tool> [--arg key=value]   # Test tools locally
npm run lint       # ESLint
npm run format     # Prettier
npm test           # Unit + integration tests (28 tests)
```

**Release:** Push a tag (e.g. `v1.0.1`) to trigger a GitHub release with built artifacts.

---

## 👤 Author

**Sergio Sediq**

- 🔗 [GitHub](https://github.com/SergioSediq)
- 💼 [LinkedIn](https://www.linkedin.com/in/sedyagho/)
- ✉️ sediqsergio@gmail.com