# monitoring-mcp-server

A **read-only** MCP server for AWS observability — EC2, EKS, RDS, ElastiCache Redis,
and CloudWatch. Built as a self-contained alternative when the official AWS MCP
servers aren't permitted. No create, modify, or delete calls exist anywhere in it.

## Tools (19)

| Area | Tools |
|------|-------|
| **EC2** | `list_ec2_instances`, `get_ec2_instance_metrics`, `get_ec2_instance_status` |
| **EKS** | `list_eks_clusters`, `list_eks_nodegroups`, `get_eks_cluster_metrics`, `get_eks_namespace_metrics`, `get_eks_service_metrics` |
| **RDS** | `list_rds_instances`, `list_rds_clusters`, `get_rds_instance_metrics` |
| **Redis** | `list_redis_clusters`, `list_redis_replication_groups`, `get_redis_metrics` |
| **CloudWatch** | `get_active_alarms`, `describe_alarms`, `get_alarm_history`, `get_metric_data`, `list_metrics` |

## Design

**One API call per health snapshot.** Metrics use `GetMetricData`, which carries up
to 500 queries per request — so `get_rds_instance_metrics` pulls 17 metrics in a
single call instead of 17 round trips.

**Adaptive periods.** CloudWatch drops fine-grained data as it ages (60s → 15 days,
300s → 63 days, 3600s → 455 days). The server picks the smallest valid period for
your window and caps the result at ~180 datapoints, so a 30-day query returns a
readable series instead of an empty one.

**Explicit gaps.** A metric with no data comes back with a `note` explaining why
rather than being silently dropped — so "healthy but idle" is distinguishable from
"metric not published for this instance family."

**Actionable errors.** Botocore exceptions map to guidance: expired SSO tokens,
missing permissions, throttling, wrong region, and unknown resource ids each get a
specific message instead of a traceback.

**Typed responses.** All tools return Pydantic models, so tool output shape is stable.

**Per-call overrides.** Every tool accepts `region` and `profile_name`; metric tools
accept `window_minutes`, `period_seconds`, and `include_datapoints`.

## Requirements

- Python 3.10+
- Credentials via the standard AWS chain (env vars, shared config, SSO, or IRSA).
- Read-only IAM: `ec2:Describe*`, `eks:List*`/`eks:Describe*`, `rds:Describe*`,
  `elasticache:Describe*`, `cloudwatch:GetMetricData`, `cloudwatch:ListMetrics`,
  `cloudwatch:DescribeAlarms`, `cloudwatch:DescribeAlarmHistory`.
  `ReadOnlyAccess` or `CloudWatchReadOnlyAccess` + service read policies cover it.

> **EKS note:** Container Insights must be enabled for `ContainerInsights` metrics.
> Without it, inventory tools still work and metric tools tell you it's disabled.

## Install

```bash
cd monitoring-mcp-server
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

export AWS_REGION=ap-south-1
export AWS_PROFILE=monitoring
```

Verify end to end (starts the server, connects as a real MCP client, calls a tool):

```bash
python test_client.py ap-south-1
```

## Client config

**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "monitoring": {
      "command": "/absolute/path/to/monitoring-mcp-server/.venv/bin/python",
      "args": ["-m", "monitoring_mcp_server.server"],
      "env": { "AWS_PROFILE": "monitoring", "AWS_REGION": "ap-south-1" }
    }
  }
}
```

**VS Code** — `.vscode/mcp.json` uses `servers` and needs `"type": "stdio"`
(see the file at the repo root).

Fully quit and reopen the client after editing. Changes to server code also
require a client restart — the client launches the process at startup.

## Example prompts

- "List stopped EC2 instances in ap-south-1."
- "Show CPU and status checks for i-0d243be7034f86ee0 over the last 6 hours."
- "Which alarms are firing, and has the API latency alarm been flapping today?"
- "Node and pod memory utilization on the prod EKS cluster."
- "RDS connections and freeable memory for orders-db over the last day."
- "Redis engine CPU, hit rate, and evictions for orders-cache-001."

## Layout

```
monitoring_mcp_server/
  aws_client.py    # client factory, profile support, error translation
  metrics.py       # GetMetricData engine, adaptive periods, MetricSpec catalogs
  models.py        # Pydantic response models
  ec2_tools.py     # EC2 inventory + metrics + status checks
  eks_tools.py     # EKS clusters, node groups, Container Insights
  rds_tools.py     # RDS instances, clusters, metrics
  redis_tools.py   # ElastiCache Redis nodes, replication groups, metrics
  alarms_tools.py  # alarms, alarm history, generic metric access
  server.py        # FastMCP entry point
test_client.py     # raw stdio MCP client for verification
```