cloudwatch-mcp

AWS CloudWatch MCP Server for security investigations – Logs Insights queries, log stream events, alarm status, and metric statistics.

Tools

| Tool | Description | |------|-------------| | query_logs | Run CloudWatch Logs Insights query against one or more log groups | | get_log_events | Retrieve raw events from a specific log stream | | list_log_groups | List available log groups (with prefix filter) | | list_log_streams | List streams in a log group, sorted by last event time | | describe_alarms | List CloudWatch alarms and their current state | | get_metric_statistics | Retrieve time-series metric statistics |

Configuration

All configuration is via environment variables:

| Variable | Required | Description | |----------|----------|-------------| | AWS_ACCESS_KEY_ID | Yes | IAM Access Key ID | | AWS_SECRET_ACCESS_KEY | Yes | IAM Secret Access Key | | AWS_DEFAULT_REGION | Yes | Target region (e.g. us-east-1) | | AWS_SESSION_TOKEN | No | Temporary credentials (AssumeRole / SSO) | | AWS_TIMEOUT | No | Request timeout ms (default: 30000) | | MAX_TOKEN_CALL | No | Token limit per response (default: 20000) |

IAM Minimum Permissions

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "logs:StartQuery",
        "logs:GetQueryResults",
        "logs:GetLogEvents",
        "logs:DescribeLogGroups",
        "logs:DescribeLogStreams",
        "cloudwatch:DescribeAlarms",
        "cloudwatch:GetMetricStatistics"
      ],
      "Resource": "*"
    }
  ]
}

Usage

Stdio (default)

AWS_ACCESS_KEY_ID=xxx AWS_SECRET_ACCESS_KEY=yyy AWS_DEFAULT_REGION=us-east-1 node dist/index.js

HTTP mode

MCP_TRANSPORT=http MCP_HTTP_PORT=3001 AWS_ACCESS_KEY_ID=xxx ... node dist/index.js

Security Investigation Examples

Query VPC Flow Logs for rejected traffic:

query_logs(
  logGroupNames: ["/aws/vpc/flowlogs"],
  queryString: "fields @timestamp, srcAddr, dstAddr, dstPort, action | filter action = 'REJECT' | sort @timestamp desc | limit 50",
  startTime: "1 hour ago"
)

Get Lambda errors:

query_logs(
  logGroupNames: ["/aws/lambda/my-function"],
  queryString: "fields @timestamp, @message | filter @message like /ERROR/ | limit 20"
)

Check active alarms:

describe_alarms(stateValue: "ALARM")

EC2 CPU spike during incident:

get_metric_statistics(
  namespace: "AWS/EC2",
  metricName: "CPUUtilization",
  dimensions: [{name: "InstanceId", value: "i-1234567890abcdef0"}],
  startTime: "2 hours ago",
  statistics: ["Maximum", "Average"]
)

License

Apache 2.0 – Copyright (c) 2024 TocharianOU Contributors