Metadata-Version: 2.4
Name: aws-health-mcp-server
Version: 1.0.1
Summary: Production-ready MCP server for monitoring AWS Health events and service status
Author-email: AWS Health MCP Team <support@example.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/jsanketh/aws-health-mcp-server
Project-URL: Repository, https://github.com/jsanketh/aws-health-mcp-server.git
Project-URL: Issues, https://github.com/jsanketh/aws-health-mcp-server/issues
Project-URL: Documentation, https://github.com/jsanketh/aws-health-mcp-server/blob/main/README.md
Keywords: aws,health,mcp,monitoring,observability
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: boto3>=1.34.0
Requires-Dist: botocore>=1.34.0
Requires-Dist: mcp[cli]>=1.3.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Dynamic: license-file

# AWS Health MCP Server

MCP server that exposes AWS Health API as tools. Works with Claude Desktop, Kiro, Amazon Q CLI, or any MCP-compatible client.

## Prerequisites

- Python 3.10+
- AWS credentials configured (`aws configure` or environment variables)
- AWS **Business or Enterprise Support** plan (required for Health API)
- For org-level tools: AWS Organizations with Health service access enabled

## Setup

Add this to your MCP config file:

- **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Kiro**: `~/.kiro/settings/mcp.json`
- **Amazon Q CLI**: `~/.aws/amazonq/mcp.json`

### Using uvx from PyPI (recommended)

```json
{
  "mcpServers": {
    "aws-health": {
      "command": "uvx",
      "args": ["aws-health-mcp-server"],
      "env": {
        "AWS_PROFILE": "default"
      }
    }
  }
}
```

### Using pip

```bash
pip install aws-health-mcp-server
```

### From a local clone

```json
{
  "mcpServers": {
    "aws-health": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/aws-health-mcp-server", "aws-health-mcp-server"],
      "env": {
        "AWS_PROFILE": "default"
      }
    }
  }
}
```

That's it. `uv` handles the venv and dependencies automatically.

## Tools

### Account-Level

| Tool | Description |
|------|-------------|
| `get_service_health` | All active health events |
| `get_affected_entities` | Resources impacted by open events |
| `get_service_events(service)` | Events for a specific service (e.g., EC2, RDS) |
| `get_completed_events(service?)` | Recently resolved events |
| `get_scheduled_changes` | Upcoming maintenance |

### Organization-Level

| Tool | Description |
|------|-------------|
| `get_org_health_events(service?, account_id?, status?)` | Events across all accounts |
| `get_org_service_health` | Active events org-wide |
| `get_org_affected_entities(account_id?, event_arn?)` | Impacted resources across accounts |
| `get_org_service_events(service)` | Service-specific events org-wide |
| `get_org_account_events(account_id)` | Events for a specific account |
| `get_org_scheduled_changes` | Org-wide scheduled maintenance |

## Example Prompts

- "Are there any active AWS health events?"
- "What's happening with EC2 right now?"
- "Show me scheduled maintenance across my organization"
- "What resources are affected by current issues in account 123456789012?"

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `AWS_PROFILE` | none | AWS credentials profile |
| `AWS_REGION` | `us-east-1` | Region (Health API is us-east-1 only) |
| `LOG_LEVEL` | `INFO` | Logging level (`DEBUG`, `INFO`, `WARNING`) |
| `HEALTH_API_TIMEOUT` | `30` | API timeout in seconds |

## Troubleshooting

**"SubscriptionRequiredException"** — You need AWS Business or Enterprise Support.

**"AccessDeniedException"** — Your IAM user/role needs `health:Describe*` permissions.

**Org tools return access error** — Enable Health service access from your management account:
```bash
aws health enable-health-service-access-for-organization
```

**Server not starting** — Check the MCP client logs. Common issues:
- Wrong Python path in config (use the full `.venv/bin/python` path)
- Missing dependencies (run `pip install -e .` in the venv)

## Development

```bash
git clone https://github.com/jsanketh/aws-health-mcp-server.git
cd aws-health-mcp-server
uv sync --extra dev
uv run pytest tests/ -v
```

## License

MIT
