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

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):

python test_client.py ap-south-1

Client config

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.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