get_metric_statistics

Retrieve CloudWatch metric statistics to monitor AWS resource performance by specifying namespace, metric name, time range, and statistical measures.

Instructions

Retrieves statistics for a specific CloudWatch metric.

Input Schema

TableJSON Schema

Name	Required	Description
`namespace`	Yes	The namespace of the metric (e.g., AWS/EC2).
`metric_name`	Yes	The name of the metric (e.g., CPUUtilization).
`dimensions`	No	Array of dimensions (e.g., [{Name: 'InstanceId', Value: 'i-xxx'}]).
`start_time`	No	Start time (ISO string).
`end_time`	No	End time (ISO string).
`period`	No	Granularity in seconds (default: 300).
`statistics`	No	Statistics to retrieve (e.g., ['Average', 'Maximum']).

Implementation Reference

src/index.ts:2098-2132 (handler)

The main handler function for the 'get_metric_statistics' tool. It constructs and sends a GetMetricStatisticsCommand to the CloudWatch client using the provided namespace, metric name, dimensions, time range, period, and statistics. Applies defaults where necessary and formats the datapoints response.

if (name === "get_metric_statistics") {
    const { namespace, metric_name, dimensions, start_time, end_time, period, statistics } = (args as any);

    // Defualts
    const actualStartTime = start_time ? new Date(start_time) : new Date(Date.now() - 24 * 60 * 60 * 1000); // 24h ago
    const actualEndTime = end_time ? new Date(end_time) : new Date();
    const actualPeriod = period || 300; // 5 mins
    const actualStats = statistics || ["Average"];

    // Convert dimensions to right format: { Name, Value } is already expected from args.

    const command = new GetMetricStatisticsCommand({
        Namespace: namespace,
        MetricName: metric_name,
        Dimensions: dimensions,
        StartTime: actualStartTime,
        EndTime: actualEndTime,
        Period: actualPeriod,
        Statistics: actualStats
    });
    const response = await cloudWatchClient.send(command);

    const datapoints = response.Datapoints?.sort((a, b) => (a.Timestamp?.getTime() || 0) - (b.Timestamp?.getTime() || 0))
        .map(dp => ({
            Timestamp: dp.Timestamp,
            Average: dp.Average,
            Maximum: dp.Maximum,
            Minimum: dp.Minimum,
            Sum: dp.Sum,
            SampleCount: dp.SampleCount,
            Unit: dp.Unit
        })) || [];

    return { content: [{ type: "text", text: JSON.stringify(datapoints, null, 2) }] };
}

src/index.ts:661-683 (registration)

Tool registration in the ListToolsRequestSchema handler, defining the tool name, description, and input schema (Zod-like structure).

{
    name: "get_metric_statistics",
    description: "Retrieves statistics for a specific CloudWatch metric.",
    inputSchema: {
        type: "object",
        properties: {
            namespace: { type: "string", description: "The namespace of the metric (e.g., AWS/EC2)." },
            metric_name: { type: "string", description: "The name of the metric (e.g., CPUUtilization)." },
            dimensions: {
                type: "array",
                items: {
                    type: "object",
                    properties: { Name: { type: "string" }, Value: { type: "string" } }
                },
                description: "Array of dimensions (e.g., [{Name: 'InstanceId', Value: 'i-xxx'}])."
            },
            start_time: { type: "string", description: "Start time (ISO string)." },
            end_time: { type: "string", description: "End time (ISO string)." },
            period: { type: "number", description: "Granularity in seconds (default: 300)." },
            statistics: { type: "array", items: { type: "string" }, description: "Statistics to retrieve (e.g., ['Average', 'Maximum'])." }
        },
        required: ["namespace", "metric_name"]
    }

src/index.ts:664-682 (schema)

Input schema definition for the get_metric_statistics tool, specifying parameters like namespace, metric_name (required), dimensions, time range, period, and statistics.

inputSchema: {
    type: "object",
    properties: {
        namespace: { type: "string", description: "The namespace of the metric (e.g., AWS/EC2)." },
        metric_name: { type: "string", description: "The name of the metric (e.g., CPUUtilization)." },
        dimensions: {
            type: "array",
            items: {
                type: "object",
                properties: { Name: { type: "string" }, Value: { type: "string" } }
            },
            description: "Array of dimensions (e.g., [{Name: 'InstanceId', Value: 'i-xxx'}])."
        },
        start_time: { type: "string", description: "Start time (ISO string)." },
        end_time: { type: "string", description: "End time (ISO string)." },
        period: { type: "number", description: "Granularity in seconds (default: 300)." },
        statistics: { type: "array", items: { type: "string" }, description: "Statistics to retrieve (e.g., ['Average', 'Maximum'])." }
    },
    required: ["namespace", "metric_name"]

src/index.ts:37-37 (helper)
Import of the AWS SDK GetMetricStatisticsCommand used by the tool handler.
```
import { GetMetricStatisticsCommand } from "@aws-sdk/client-cloudwatch";
```

AWS MCP Server