Amazon CloudWatch

Amazon CloudWatch MCP Server

Metrics, alarms, and logs analysis.

What is an MCP Server?

MCP Info

Image Building Info

Available Tools (19)

Tools Details

Tool: analyze_log_group

Analyzes a CloudWatch log group for anomalies, message patterns, and error patterns within a specified time window.

This tool performs an analysis of the specified log group by:

1. Discovering and checking log anomaly detectors associated with the log group
2. Retrieving anomalies from those detectors that fall within the specified time range
3. Identifying the top 5 most common message patterns
4. Finding the top 5 patterns containing error-related terms

Usage: Use this tool to detect anomalies and understand common patterns in your log data, particularly focusing on error patterns that might indicate issues. This can help identify potential problems and understand the typical behavior of your application.

Returns:

A LogsAnalysisResult object containing: - log_anomaly_results: Information about anomaly detectors and their findings * anomaly_detectors: List of anomaly detectors for the log group * anomalies: List of anomalies that fall within the specified time range - top_patterns: Results of the query for most common message patterns - top_patterns_containing_errors: Results of the query for patterns containing error-related terms (error, exception, fail, timeout, fatal)

Tool: analyze_metric

Analyzes CloudWatch metric data to determine seasonality, trend, data density and statistical properties.

This tool provides RAW DATA ONLY about historical metric data and performs analysis including:

• Seasonality detection
• Trend analysis
• Data density and publishing period
• Advanced statistical measures (min/max/median, std dev, noise)

Usage: Use this tool to get objective metric analysis data.

Tool: cancel_logs_insight_query

Cancels an ongoing CloudWatch Logs Insights query. If the query has already ended, returns an error that the given query is not running.

Usage: If a log query is started by execute_log_insights_query tool and has a polling time out, this tool can be used to cancel it prematurely to avoid incurring additional costs.

Returns:

A LogsQueryCancelResult with a "success" key, which is True if the query was successfully cancelled.

Tool: describe_log_groups

Lists AWS CloudWatch log groups and saved queries associated with them, optionally filtering by a name prefix.

This tool retrieves information about log groups in the account, or log groups in accounts linked to this account as a monitoring account. If a prefix is provided, only log groups with names starting with the specified prefix are returned.

Additionally returns any user saved queries that are associated with any of the returned log groups.

Usage: Use this tool to discover log groups that you'd retrieve or query logs from and queries that have been saved by the user.

Returns:

List of log group metadata dictionaries and saved queries associated with them Each log group metadata contains details such as: - logGroupName: The name of the log group. - creationTime: Timestamp when the log group was created - retentionInDays: Retention period, if set - storedBytes: The number of bytes stored. - kmsKeyId: KMS Key Id used for data encryption, if set - dataProtectionStatus: Displays whether this log group has a protection policy, or whether it had one in the past, if set - logGroupClass: Type of log group class - logGroupArn: The Amazon Resource Name (ARN) of the log group. This version of the ARN doesn't include a trailing :* after the log group name. Any saved queries that are applicable to the returned log groups are also included.

            If this parameter is set to true and account_identifiers contains a null value, the tool returns all log groups in the monitoring account and all log groups in all source accounts that are linked to the monitoring account.

log_group_class|string optional|If specified, filters for only log groups of the specified class. log_group_name_prefix|string optional|An exact prefix to filter log groups by name. IMPORTANT: Only log groups with names starting with this prefix will be returned. max_items|string optional|The maximum number of log groups to return. profile_name|string optional|AWS CLI Profile Name to use for AWS access. Falls back to AWS_PROFILE environment variable if not specified, or uses default AWS credential chain. region|string optional|AWS region to query. Defaults to AWS_REGION environment variable or us-east-1 if not set.

Tool: execute_cwl_insights_batch

Run a CloudWatch Logs Insights query across multiple log groups, accounts, and regions.

Automatically chunks log groups (max 50 per StartQuery), throttles concurrency to 25% of account limits, retries transient failures, and splits time ranges on 10k-record or timeout hits (up to 4 levels). Results are annotated with _region, _logGroups, and optionally _account metadata.

For simple single-region queries on a few log groups, use execute_log_insights_query instead.

Raises: ValueError: If input parameters are invalid (e.g. start_time >= end_time).

Tool: execute_log_insights_query

Executes a CloudWatch Logs Insights query and waits for the results to be available.

IMPORTANT: The operation must include exactly one of the following parameters: log_group_names, or log_group_identifiers.

CRITICAL: The volume of returned logs can easily overwhelm the agent context window. Always include a limit in the query (| limit 50) or using the limit parameter.

Usage: Use to query, filter, collect statistics, or find patterns in one or more log groups. For example, the following query lists exceptions per hour.

filter @message like /Exception/
| stats count(*) as exceptionCount by bin(1h)
| sort exceptionCount desc

Returns:

A dictionary containing the final query results, including:
    - status: The current status of the query (e.g., Scheduled, Running, Complete, Failed, etc.)
    - results: A list of the actual query results if the status is Complete.
    - statistics: Query performance statistics
    - messages: Any informational messages about the query

Tool: execute_promql_query

Execute an instant PromQL query against CloudWatch.

Returns the current value of metrics at a single point in time (instant vector). For time series over a range, use execute_promql_range_query instead.

Use this tool when:

• The user provides a PromQL expression
• The user references OTLP-ingested metrics or labels (@resource., @aws., @instrumentation.*)
• The user asks about enriched vended AWS metrics with OTel labels
• The user wants to query by AWS resource tags (@aws.tag.*)

Use get_metric_data instead when:

• The user references classic CloudWatch namespaces/dimensions (AWS/EC2, etc.)
• The user wants Metrics Insights SQL syntax

PromQL label conventions (OTLP scope to label mapping):

• @resource.{attr} - OTel resource attributes (e.g., @resource.service.name="myservice")
• @instrumentation.{attr} - instrumentation scope (e.g., @instrumentation.@name="cloudwatch.aws/ec2")
• @datapoint.{attr} or bare - datapoint attributes / CW dimensions (e.g., InstanceId="i-xxx")
• @aws.account_id, @aws.region - AWS system labels
• @aws.tag.{Key} - AWS resource tags (e.g., @aws.tag.Environment="production", @aws.tag.Team="backend")

For enriched vended AWS metrics, use histogram functions (OTel enrichment must be enabled first: aws cloudwatch start-otel-enrichment):

• histogram_avg({CPUUtilization, "@instrumentation.@name"="cloudwatch.aws/ec2"})
• histogram_sum({Invocations, FunctionName="my-func"})

Limits: max 500 series returned, 7-day range, 20s timeout.

Example queries:

• {"http.server.active_requests", "@resource.service.name"="myservice"}
• histogram_avg({CPUUtilization, "@instrumentation.@name"="cloudwatch.aws/ec2"})
• sum by ("@aws.tag.Team")(histogram_sum({Invocations, "@instrumentation.@name"="cloudwatch.aws/lambda"}))

Tool: execute_promql_range_query

Execute a PromQL range query against CloudWatch.

Returns time series data over a time range (matrix). Use for trend analysis and graphs.

Use this tool when:

• The user provides a PromQL expression and wants data over a time window
• The user references OTLP-ingested metrics or labels (@resource., @aws., @instrumentation.*)
• The user asks about enriched vended AWS metrics with OTel labels

Use get_metric_data instead when:

• The user references classic CloudWatch namespaces/dimensions (AWS/EC2, etc.)
• The user wants Metrics Insights SQL syntax

For enriched vended AWS metrics, use histogram functions (OTel enrichment must be enabled first: aws cloudwatch start-otel-enrichment):

• histogram_avg({CPUUtilization, "@instrumentation.@name"="cloudwatch.aws/ec2"})
• histogram_sum({Errors, "@instrumentation.@name"="cloudwatch.aws/lambda", "@aws.tag.Team"="backend"})

Limits: max 500 series, max 7-day range (including lookback), 20s timeout.

Example: query: 'avg_over_time({"http.server.active_requests", "@resource.service.name"="myservice"}[5m])' start: "2024-01-01T00:00:00Z" end: "2024-01-01T01:00:00Z" step: "5m"

Tool: get_active_alarms

Gets all CloudWatch Alarms currently in ALARM state.

This tool retrieves all CloudWatch Alarms that are currently in the ALARM state, including both metric alarms and composite alarms. Results are optimized for LLM reasoning with summary-level information.

Usage: Use this tool to get an overview of all active alarms in your AWS account for troubleshooting, monitoring, and operational awareness.

Tool: get_alarm_history

Gets the history for a CloudWatch alarm with time range suggestions for investigation.

This tool retrieves the history for a specified CloudWatch alarm, focusing primarily on state transitions to ALARM state. It also provides suggested time ranges for investigation based on the alarm's configuration and history.

Usage: Use this tool to understand when an alarm fired and get useful time ranges for investigating the underlying issue using other CloudWatch tools. The tool is particularly useful for identifying patterns like alarm flapping (going in and out of alarm state frequently).

Tool: get_logs_insight_query_results

Retrieves the results of a previously started CloudWatch Logs Insights query.

Usage: If a log query is started by execute_log_insights_query tool and has a polling time out, this tool can be used to try to retrieve the query results again.

Returns:

A dictionary containing the final query results, including:
    - status: The current status of the query (e.g., Scheduled, Running, Complete, Failed, etc.)
    - results: A list of the actual query results if the status is Complete.
    - statistics: Query performance statistics
    - messages: Any informational messages about the query

Tool: get_metric_data

Retrieves CloudWatch metric data for a specific metric.

This tool retrieves metric data from CloudWatch for a specific metric identified by its namespace, metric name, and dimensions, within a specified time range. It can use either standard GetMetricData API or CloudWatch Metrics Insights for more advanced querying.

The function automatically determines whether to use standard GetMetricData or Metrics Insights based on the parameters provided. If any Metrics Insights specific parameters are provided (group_by_dimension, schema_dimension_keys, limit, sort_order, or order_by_statistic), it will use Metrics Insights.

When using group_by_dimension, you must include that dimension in schema_dimension_keys.

For advanced use cases, the optional queries parameter accepts a list of MetricDataQueryInput objects and unlocks capabilities that the single-metric path cannot express: percentile statistics (p50, p90, p99...), metric math expressions (e.g. errors / invocations), and multi-metric batching (retrieving many metrics in a single API call). When queries is provided, namespace, metric_name, dimensions, and statistic are not used.

start_time is optional; when omitted, it defaults to 3 hours before end_time (which itself defaults to the current UTC time).

Usage: Use this tool to get actual metric data from CloudWatch for analysis or visualization.

Returns: GetMetricDataResponse: An object containing the metric data results

Example 1 (Standard GetMetricData): result = await get_metric_data( ctx, namespace="AWS/EC2", metric_name="CPUUtilization", start_time="2023-01-01T00:00:00Z", dimensions=[ Dimension(name="InstanceId", value="i-1234567890abcdef0") ], statistic="Average" # Period will be auto-calculated based on time window and target_datapoints )

Example 2 (Metrics Insights with group by): result = await get_metric_data( ctx, namespace="AWS/EC2", metric_name="CPUUtilization", start_time="2023-01-01T00:00:00Z", end_time="2023-01-02T00:00:00Z", statistic="AVG", schema_dimension_keys=["InstanceType"], group_by_dimension="InstanceType" # This will generate a query like: SELECT AVG("CPUUtilization") FROM SCHEMA("AWS/EC2", "InstanceType") GROUP BY "InstanceType" )

Example 3 (Metrics Insights with schema dimension keys): result = await get_metric_data( ctx, namespace="AWS/EC2", metric_name="CPUUtilization", start_time="2023-01-01T00:00:00Z", end_time="2023-01-02T00:00:00Z", statistic="AVG", schema_dimension_keys=["InstanceId", "InstanceType"], group_by_dimension="InstanceId" # This will generate a query like: SELECT AVG("CPUUtilization") FROM SCHEMA("AWS/EC2", "InstanceId", "InstanceType") GROUP BY "InstanceId" )

Example 4 (Metrics Insights with ORDER BY and LIMIT to find the top 5 EC2 instances with the highest CPU utilization): result = await get_metric_data( ctx, namespace="AWS/EC2", metric_name="CPUUtilization", start_time="2023-01-01T00:00:00Z", end_time="2023-01-02T00:00:00Z", statistic="AVG", schema_dimension_keys=["InstanceId"], group_by_dimension="InstanceId", sort_order="DESC", limit=5, order_by_statistic="MAX" # This will generate a query like: SELECT AVG("CPUUtilization") FROM SCHEMA("AWS/EC2", "InstanceId") GROUP BY "InstanceId" ORDER BY MAX() DESC LIMIT 5 )

Example 5 (Metrics Insights with ORDER BY without sort direction to find the EC2 instances with the highest CPU utilization ordered by default ASC): result = await get_metric_data( ctx, namespace="AWS/EC2", metric_name="CPUUtilization", start_time="2023-01-01T00:00:00Z", end_time="2023-01-02T00:00:00Z", statistic="AVG", schema_dimension_keys=["InstanceId"], group_by_dimension="InstanceId", order_by_statistic="MAX" # This will generate a query like: SELECT AVG("CPUUtilization") FROM SCHEMA("AWS/EC2", "InstanceId") GROUP BY "InstanceId" ORDER BY MAX() )

Example 6 (Metrics Insights without ORDER BY clause to find the EC2 instances with the highest CPU utilization in no specific order): result = await get_metric_data( ctx, namespace="AWS/EC2", metric_name="CPUUtilization", start_time="2023-01-01T00:00:00Z", end_time="2023-01-02T00:00:00Z", statistic="AVG", schema_dimension_keys=["InstanceId"], group_by_dimension="InstanceId" # This will generate a query like: SELECT AVG("CPUUtilization") FROM SCHEMA("AWS/EC2", "InstanceId") GROUP BY "InstanceId" # No ORDER BY clause is added since neither order_by_statistic nor sort_order is specified )

For each result: for metric_result in result.metricDataResults: print(f"Metric: {metric_result.label}") for datapoint in metric_result.datapoints: print(f" {datapoint.timestamp}: {datapoint.value}")

Example 7 (Advanced queries - Lambda Latency Percentiles): Use the queries parameter for percentile statistics (p50, p90, p99).

result = await get_metric_data(
    ctx,
    start_time="2025-12-21T00:00:00Z",
    queries=[
        MetricDataQueryInput(
            id="p50",
            metric_stat=MetricStatInput(
                namespace="AWS/Lambda",
                metric_name="Duration",
                dimensions=[Dimension(name="FunctionName", value="my-api-function")],
                statistic="p50"
            ),
            label="Median Latency"
        ),
        MetricDataQueryInput(
            id="p99",
            metric_stat=MetricStatInput(
                namespace="AWS/Lambda",
                metric_name="Duration",
                dimensions=[Dimension(name="FunctionName", value="my-api-function")],
                statistic="p99"
            ),
            label="p99 Latency"
        )
    ]
)

Example 8 (Advanced queries - Error Rate Calculation with Math Expression): Use queries with math expressions to calculate derived metrics.

result = await get_metric_data(
    ctx,
    start_time="2025-12-21T00:00:00Z",
    queries=[
        MetricDataQueryInput(
            id="errors",
            metric_stat=MetricStatInput(
                namespace="AWS/Lambda",
                metric_name="Errors",
                dimensions=[Dimension(name="FunctionName", value="my-api-function")],
                statistic="Sum"
            ),
            return_data=False  # Don't include raw errors in results
        ),
        MetricDataQueryInput(
            id="invocations",
            metric_stat=MetricStatInput(
                namespace="AWS/Lambda",
                metric_name="Invocations",
                dimensions=[Dimension(name="FunctionName", value="my-api-function")],
                statistic="Sum"
            ),
            return_data=False  # Don't include raw invocations in results
        ),
        MetricDataQueryInput(
            id="error_rate",
            expression="(errors / invocations) * 100",
            label="Error Rate %"
        )
    ]
)
# Result contains only the calculated error_rate percentage

Tool: get_metric_metadata

Gets metadata for a CloudWatch metric including description, unit and recommended statistics that can be used for metric data retrieval.

This tool retrieves comprehensive metadata about a specific CloudWatch metric identified by its namespace and metric name. Note: This function uses local metadata and does not make AWS API calls.

Usage: Use this tool to get detailed information about CloudWatch metrics, including their descriptions, units, and recommended statistics to use.

Tool: get_promql_label_values

Get values for a specific PromQL label from CloudWatch.

Use label_name="name" to list all available metric names. Use label_name="@resource.service.name" to list all services.

Use this tool when:

• The user wants to discover available metrics via PromQL
• The user wants to see what values exist for a label
• The user is exploring OTLP-ingested or enriched vended metrics

Limits: max 10,000 values returned per request.

Examples:

• label_name="name" → list all metric names
• label_name="@resource.service.name" → list all service names
• label_name="@instrumentation.@name" → list all instrumentation scopes
• label_name="@aws.tag.Environment" → list all Environment tag values

Tool: get_promql_labels

Get all label names available in CloudWatch PromQL.

Returns a list of all label names. Useful for discovering the label structure of OTLP-ingested metrics and enriched vended AWS metrics.

Use this tool when:

• The user wants to know what labels/dimensions are available
• The user is exploring the label structure of their metrics

Common labels include:

• name (metric name)
• @resource.service.name, @resource.cloud.region, @resource.cloud.account.id (OTel resource attributes)
• @instrumentation.@name (instrumentation scope, e.g., "cloudwatch.aws/ec2", "cloudwatch.aws/lambda")
• @aws.account_id, @aws.region (AWS system labels)
• @aws.tag.{Key} (AWS resource tags, e.g., @aws.tag.Environment, @aws.tag.Team)
• Bare dimension names (e.g., InstanceId, FunctionName) — these are datapoint attributes

Limits: max 10,000 labels returned per request.

Tool: get_promql_series

Find time series matching label selectors in CloudWatch.

Returns the label sets of all series matching the provided matchers. Useful for discovering what series exist and their label structure.

Use this tool when:

• The user wants to explore what time series exist for a metric
• The user wants to see the full label set of matching series
• The user is investigating OTLP-ingested or enriched vended metrics

Limits: max 10,000 series returned per request.

Example: match: ['{"@instrumentation.@name"="cloudwatch.aws/ec2"}']

Tool: get_recommended_metric_alarms

Gets recommended alarms for a CloudWatch metric.

This tool retrieves alarm recommendations for a specific CloudWatch metric identified by its namespace, metric name, and dimensions. The recommendations are filtered to match the provided dimensions.

Usage: Use this tool to get recommended alarm configurations for CloudWatch metrics, including thresholds, evaluation periods, and other alarm settings.

Tool: recommend_indexes_account

Triage tool: find which log groups would benefit from field indexing.

Scans the last 30 days of completed Logs Insights queries across the account, groups by log group, and identifies frequently queried but unindexed fields. Lightweight scan — no per-log-group Insights queries. Use recommend_indexes_loggroup for full analysis on specific log groups.

Tool: recommend_indexes_loggroup

Recommend field indexes for a specific CloudWatch log group.

Analyzes the last 30 days of completed Logs Insights queries (CWLI, SQL, PPL), identifies which fields would benefit most from indexing, and returns prioritized recommendations scored by: query frequency (30%), equality filter usage (25%), recency (15%), scan volume (15%), cardinality of top 10 (15%).

Use recommend_indexes_account first to identify which log groups to analyze.

Use this MCP Server

{
  "mcpServers": {
    "awslabs-cloudwatch": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "AWS_REGION",
        "-e",
        "AWS_PROFILE",
        "mcp/cloudwatch-mcp-server"
      ],
      "env": {
        "AWS_REGION": "us-east-1",
        "AWS_PROFILE": "default"
      }
    }
  }
}

Why is it safer to run MCP Servers with Docker?