MCP Server AWS CloudWatch — metrics, logs, alarms, and Logs Insights

SDK setup: singleton clients

The AWS SDK v3 for JavaScript splits CloudWatch into two separate clients: @aws-sdk/client-cloudwatch for metrics and alarms, and @aws-sdk/client-cloudwatch-logs for log groups. Create both as module-level singletons — the SDK resolves credentials from the credential chain (environment variables → ~/.aws/credentials → EC2/ECS instance profile) once at construction time and re-uses the resolved credentials across all commands.

import { CloudWatchClient } from '@aws-sdk/client-cloudwatch';
import { CloudWatchLogsClient } from '@aws-sdk/client-cloudwatch-logs';

const REGION = process.env.AWS_REGION ?? 'us-east-1';

// Singleton clients — constructed once, shared across all tool calls
export const cw = new CloudWatchClient({ region: REGION });
export const cwl = new CloudWatchLogsClient({ region: REGION });

// Credentials are resolved from the credential chain:
// 1. AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY + AWS_SESSION_TOKEN env vars
// 2. ~/.aws/credentials file (profile selected by AWS_PROFILE)
// 3. ECS task role / EC2 instance profile (automatically rotated by AWS)

Avoid constructing new clients inside tool handlers. The credential chain resolution involves network calls for IAM roles and adds 100–500ms of latency per tool invocation when done inside the handler. Module-level singletons pay this cost once at startup.

query_metrics tool: GetMetricStatistics

GetMetricStatisticsCommand returns time-series data for a single metric. It requires a namespace, metric name, time window, and period (the granularity of each data point in seconds). Dimensions narrow the query to a specific resource — for example, InstanceId for EC2 CPUUtilization or FunctionName for Lambda errors.

import { z } from 'zod';
import {
  GetMetricStatisticsCommand,
  Statistic
} from '@aws-sdk/client-cloudwatch';
import { cw } from './aws-clients.js';

server.tool(
  'query_cloudwatch_metric',
  {
    namespace: z.string().min(1),        // e.g. 'AWS/EC2', 'AWS/Lambda', 'AWS/RDS'
    metric_name: z.string().min(1),      // e.g. 'CPUUtilization', 'Errors', 'Duration'
    dimension_name: z.string().optional(),   // e.g. 'InstanceId', 'FunctionName'
    dimension_value: z.string().optional(),  // e.g. 'i-0abc123', 'my-function'
    start_time: z.string().datetime(),   // ISO-8601, e.g. '2026-07-04T00:00:00Z'
    end_time: z.string().datetime(),
    period_seconds: z.number().int().min(60).default(300),  // min 60s; must be divisible by 60
    statistic: z.enum(['Average', 'Sum', 'Minimum', 'Maximum', 'SampleCount']).default('Average')
  },
  async ({ namespace, metric_name, dimension_name, dimension_value,
           start_time, end_time, period_seconds, statistic }) => {
    const dimensions = dimension_name && dimension_value
      ? [{ Name: dimension_name, Value: dimension_value }]
      : [];

    const result = await cw.send(new GetMetricStatisticsCommand({
      Namespace: namespace,
      MetricName: metric_name,
      Dimensions: dimensions,
      StartTime: new Date(start_time),
      EndTime: new Date(end_time),
      Period: period_seconds,
      Statistics: [statistic as Statistic]
    }));

    // Sort by timestamp ascending (CloudWatch returns in arbitrary order)
    const datapoints = (result.Datapoints ?? [])
      .sort((a, b) => (a.Timestamp?.getTime() ?? 0) - (b.Timestamp?.getTime() ?? 0))
      .map((dp) => ({
        timestamp: dp.Timestamp?.toISOString(),
        value: dp[statistic as keyof typeof dp],
        unit: dp.Unit
      }));

    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          namespace,
          metric_name,
          statistic,
          period_seconds,
          datapoints,
          datapoint_count: datapoints.length
        }, null, 2)
      }]
    };
  }
);

CloudWatch returns datapoints in arbitrary order — always sort by Timestamp in your tool before returning. The Period must be a multiple of 60 seconds; for high-resolution metrics published at sub-minute intervals, use GetMetricDataCommand with a MetricDataQuery instead — it supports periods as low as 1 second for metrics stored at high resolution.

list_alarms and get_alarm_history tools

CloudWatch Alarms are the primary alerting mechanism for AWS metrics. The DescribeAlarmsCommand lists alarms with optional state and name prefix filters. Alarm state transitions are logged in alarm history.

import {
  DescribeAlarmsCommand,
  DescribeAlarmHistoryCommand,
  StateValue
} from '@aws-sdk/client-cloudwatch';

server.tool(
  'list_cloudwatch_alarms',
  {
    state: z.enum(['OK', 'ALARM', 'INSUFFICIENT_DATA']).optional(),
    name_prefix: z.string().optional(),
    max_results: z.number().int().min(1).max(100).default(20)
  },
  async ({ state, name_prefix, max_results }) => {
    const result = await cw.send(new DescribeAlarmsCommand({
      StateValue: state as StateValue | undefined,
      AlarmNamePrefix: name_prefix,
      MaxRecords: max_results
    }));

    const alarms = (result.MetricAlarms ?? []).map((alarm) => ({
      name: alarm.AlarmName,
      state: alarm.StateValue,
      reason: alarm.StateReason,
      updated_at: alarm.StateUpdatedTimestamp?.toISOString(),
      namespace: alarm.Namespace,
      metric: alarm.MetricName,
      threshold: alarm.Threshold,
      comparison: alarm.ComparisonOperator
    }));

    return {
      content: [{
        type: 'text',
        text: JSON.stringify({ alarms, count: alarms.length }, null, 2)
      }]
    };
  }
);

server.tool(
  'get_alarm_history',
  {
    alarm_name: z.string().min(1),
    start_time: z.string().datetime().optional(),
    end_time: z.string().datetime().optional()
  },
  async ({ alarm_name, start_time, end_time }) => {
    const result = await cw.send(new DescribeAlarmHistoryCommand({
      AlarmName: alarm_name,
      StartDate: start_time ? new Date(start_time) : undefined,
      EndDate: end_time ? new Date(end_time) : undefined,
      MaxRecords: 50
    }));

    const events = (result.AlarmHistoryItems ?? []).map((item) => ({
      timestamp: item.Timestamp?.toISOString(),
      type: item.HistoryItemType,
      summary: item.HistorySummary
    }));

    return {
      content: [{
        type: 'text',
        text: JSON.stringify({ alarm_name, events }, null, 2)
      }]
    };
  }
);

Alarm state INSUFFICIENT_DATA means CloudWatch has not received enough data points to evaluate the alarm — this is common when a metric is published at a lower frequency than the alarm's evaluation period. It does not mean the resource is down; the alarm is simply waiting for data.

Logs Insights: start_query and poll for results

CloudWatch Logs Insights runs SQL-like queries asynchronously. The pattern is: StartQueryCommand to submit the query and get a query ID, then poll GetQueryResultsCommand until the status is Complete. Do not use FilterLogEventsCommand for complex queries — it's a simple text filter that scans the log stream sequentially and returns raw log events without aggregation or field parsing.

import {
  StartQueryCommand,
  GetQueryResultsCommand
} from '@aws-sdk/client-cloudwatch-logs';
import { cwl } from './aws-clients.js';

server.tool(
  'query_cloudwatch_logs',
  {
    log_group: z.string().min(1),       // e.g. '/aws/lambda/my-function'
    query_string: z.string().min(1),    // Logs Insights syntax
    start_time: z.string().datetime(),
    end_time: z.string().datetime(),
    limit: z.number().int().min(1).max(1000).default(100)
  },
  async ({ log_group, query_string, start_time, end_time, limit }) => {
    // Submit the query
    const startResult = await cwl.send(new StartQueryCommand({
      logGroupName: log_group,
      queryString: query_string,
      startTime: Math.floor(new Date(start_time).getTime() / 1000),
      endTime: Math.floor(new Date(end_time).getTime() / 1000),
      limit
    }));

    const queryId = startResult.queryId;
    if (!queryId) throw new Error('CloudWatch Logs Insights did not return a query ID');

    // Poll for completion (up to 30 seconds)
    let status = 'Running';
    let results: Record[] = [];
    const deadline = Date.now() + 30_000;

    while (status === 'Running' || status === 'Scheduled') {
      if (Date.now() > deadline) {
        return {
          content: [{
            type: 'text',
            text: JSON.stringify({ error: 'Query timed out after 30s', queryId })
          }]
        };
      }
      await new Promise((r) => setTimeout(r, 1500));

      const pollResult = await cwl.send(new GetQueryResultsCommand({ queryId }));
      status = pollResult.status ?? 'Unknown';
      results = (pollResult.results ?? []).map((row) =>
        Object.fromEntries((row ?? []).map((f) => [f.field ?? '', f.value ?? '']))
      );
    }

    return {
      content: [{
        type: 'text',
        text: JSON.stringify({ queryId, status, row_count: results.length, results }, null, 2)
      }]
    };
  }
);

Health endpoint: /health/cloudwatch

The most common failure mode for CloudWatch MCP tools is expired IAM credentials. A process-level HTTP check passes even when the IAM session token has expired — the process is running fine, but every CloudWatch API call will return a 403 ExpiredTokenException. A lightweight CloudWatch API probe catches this before tool callers see errors.

import express from 'express';
import { ListMetricsCommand } from '@aws-sdk/client-cloudwatch';

const app = express();

app.get('/health/cloudwatch', async (_req, res) => {
  const start = Date.now();
  try {
    // Minimal IAM action: cloudwatch:ListMetrics
    // Returns quickly when namespaced to a specific service
    await cw.send(new ListMetricsCommand({
      Namespace: 'AWS/EC2',
      RecentlyActive: 'PT3H'  // only metrics active in last 3 hours — limits response size
    }));

    res.status(200).json({
      status: 'ok',
      latency_ms: Date.now() - start,
      region: REGION
    });
  } catch (err) {
    const error = err as { name?: string; message?: string };
    res.status(503).json({
      status: 'error',
      error_type: error.name,   // 'ExpiredTokenException', 'AccessDeniedException', etc.
      error: error.message,
      latency_ms: Date.now() - start
    });
  }
});

app.listen(3001);

Minimum IAM policy

CloudWatch MCP tools should use the minimum IAM permissions needed. The policy below covers all tools in this guide — separate statements for metrics, logs, and alarms.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CloudWatchMetricsReadOnly",
      "Effect": "Allow",
      "Action": [
        "cloudwatch:GetMetricStatistics",
        "cloudwatch:GetMetricData",
        "cloudwatch:ListMetrics",
        "cloudwatch:DescribeAlarms",
        "cloudwatch:DescribeAlarmHistory"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CloudWatchLogsReadOnly",
      "Effect": "Allow",
      "Action": [
        "logs:FilterLogEvents",
        "logs:StartQuery",
        "logs:GetQueryResults",
        "logs:DescribeLogGroups",
        "logs:DescribeLogStreams"
      ],
      "Resource": "arn:aws:logs:*:*:log-group:*"
    }
  ]
}

Do not grant cloudwatch:PutMetricAlarm or logs:PutLogEvents unless your tools explicitly need to create alarms or write logs. Read-only access is sufficient for all query and alert-inspection use cases.

Frequently asked questions

Further reading

• MCP Server AWS S3 — object storage tools and IAM credential patterns
• MCP Server Datadog — metrics, monitors, and APM service map tools
• MCP Server OpenTelemetry — tracing and metrics instrumentation
• MCP Server PagerDuty — incident management and on-call tools
• MCP Server Health Check — wiring /health endpoints for uptime monitoring