awslabs.cloudwatch-mcp-server 0.1.2

An AWS Labs Model Context Protocol (MCP) server for cloudwatch

AWS Labs CloudWatch MCP Server

This AWS Labs Model Context Protocol (MCP) server for CloudWatch enables your troubleshooting agents to use CloudWatch data to do AI-powered root cause analysis and provide recommendations. It offers comprehensive observability tools that simplify monitoring, reduce context switching, and help teams quickly diagnose and resolve service issues. This server will provide AI agents with seamless access to CloudWatch telemetry data through standardized MCP interfaces, eliminating the need for custom API integrations and reducing context switching during troubleshooting workflows. By consolidating access to all CloudWatch capabilities, we enable powerful cross-service correlations and insights that accelerate incident resolution and improve operational visibility.

Instructions

The CloudWatch MCP Server provides specialized tools to address common operational scenarios including alarm troubleshooting, understand metrics definitions, alarm recommendations and log analysis. Each tool encapsulates one or multiple CloudWatch APIs into task-oriented operations.

Features

Alarm Based Troubleshooting - Identifies active alarms, retrieves related metrics and logs, and analyzes historical alarm patterns to determine root causes of triggered alerts. Provides context-aware recommendations for remediation.

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

Metric Definition Analyzer - Provides comprehensive descriptions of what metrics represent, how they're calculated, recommended statistics to use for metric data retrieval

Alarm Recommendations - Suggests recommended alarm configurations for CloudWatch metrics, including thresholds, evaluation periods, and other alarm settings.

Prerequisites

1. An AWS account with CloudWatch Telemetry
2. This MCP server can only be run locally on the same host as your LLM client.
3. Set up AWS credentials with access to AWS services
   • You need an AWS account with appropriate permissions (See required permissions below)
   • Configure AWS credentials with aws configure or environment variables

Available Tools

Tools for CloudWatch Metrics

• get_metric_data - Retrieves detailed CloudWatch metric data for any CloudWatch metric. Use this for general CloudWatch metrics that aren't specific to Application Signals. Provides ability to query any metric namespace, dimension, and statistic
• get_metric_metadata - Retrieves comprehensive metadata about a specific CloudWatch metric
• get_recommended_metric_alarms - Gets recommended alarms for a CloudWatch metric based on best practice, and trend, seasonality and statistical analysis.
• analyze_metric - Analyzes CloudWatch metric data to determine trend, seasonality, and statistical properties

Tools for CloudWatch PromQL

• execute_promql_query - Executes an instant PromQL query against CloudWatch, returning metric values at a single point in time. Use for OTLP-ingested metrics, enriched vended AWS metrics, and queries using PromQL label syntax (@resource.*, @aws.*, @instrumentation.*).
• execute_promql_range_query - Executes a PromQL range query over a time window, returning time series data (matrix). Use for trend analysis and graphs with PromQL syntax.
• get_promql_label_values - Gets values for a specific PromQL label (e.g., __name__ for metric names, @resource.service.name for services). Use for metric discovery.
• get_promql_series - Finds time series matching PromQL label selectors. Returns the full label set of matching series.
• get_promql_labels - Lists all available PromQL label names. Use to discover the label structure of OTLP-ingested and enriched vended metrics.

Note: PromQL tools are available in: us-east-1, us-west-2, eu-west-1, ap-southeast-1, ap-southeast-2. For enriched vended AWS metrics, OTel enrichment must be enabled first (aws cloudwatch start-otel-enrichment). Vended metrics are histograms — use histogram_avg(), histogram_sum(), etc. Use @instrumentation.@name to disambiguate metrics across services (e.g., "cloudwatch.aws/ec2" vs "cloudwatch.aws/rds").

OTLP scope to PromQL label mapping:

OTLP Scope	Attributes prefix	Example
Resource	@resource.	@resource.service.name="myservice"
Instrumentation Scope	@instrumentation.	@instrumentation.@name="cloudwatch.aws/ec2"
Datapoint	@datapoint. or bare	InstanceId="i-xxx" or @datapoint.InstanceId="i-xxx"
AWS system labels	@aws.	@aws.account_id="123456789012", @aws.region="us-east-1"
AWS resource tags	@aws.tag.	@aws.tag.Environment="production", @aws.tag.Team="backend"

Tools for CloudWatch Alarms

• get_active_alarms - Identifies currently active CloudWatch alarms across the account
• get_alarm_history - Retrieves historical state changes and patterns for a given CloudWatch alarm

Tools for CloudWatch Logs

• describe_log_groups - Finds metadata about CloudWatch log groups
• analyze_log_group - Analyzes CloudWatch logs for anomalies, message patterns, and error patterns
• execute_log_insights_query - Executes CloudWatch Logs insights query on CloudWatch log group(s) with specified time range and query syntax, returns a unique ID used to retrieve results
• execute_cwl_insights_batch - Runs a Logs Insights query across multiple log groups and regions in a single call, automatically chunking log groups (max 50 per query), throttling concurrency (max 7 per region), polling for completion, retrying failures, and splitting time ranges when hitting the 10,000-record or timeout limits. Returns one merged result set annotated with region, log group, and optional account labels. See execute_cwl_insights_batch Examples below.
• get_logs_insight_query_results - Retrieves the results of an executed CloudWatch insights query using the query ID. It is used after execute_log_insights_query has been called
• cancel_logs_insight_query - Cancels in progress CloudWatch logs insights query

execute_cwl_insights_batch Examples

Basic usage:

result = await execute_cwl_insights_batch(
    ctx,
    log_group_names=['/aws/lambda/my-app'],  # Log group names (or ARNs for cross-account/region)
    regions=['us-east-1', 'us-west-2', 'eu-west-1'],  # Regions to query
    start_time='2025-04-19T20:00:00+00:00',  # ISO 8601 start time with timezone
    end_time='2025-04-19T21:00:00+00:00',  # ISO 8601 end time with timezone
    query_string='fields @timestamp, @message | filter @message like /ERROR/ | limit 100'  # Logs Insights query
)

print(f"Found {result.summary.total_records_returned} errors across {result.summary.total_regions} regions")
for warning in result.summary.warnings:
    print(f"Warning: {warning}")

Cross-account/cross-region query using log group ARNs:

# When querying log groups in different accounts or regions, use ARN format:
# arn:aws:logs:<region>:<account-id>:log-group:<log-group-name>
result = await execute_cwl_insights_batch(
    ctx,
    log_group_names=[
        'arn:aws:logs:us-east-1:123456789012:log-group:/aws/ecs/my-service',  # Source account log group ARN
        'arn:aws:logs:eu-west-1:123456789012:log-group:/aws/ecs/my-service'   # Different region
    ],
    regions=['us-east-1'],  # Monitoring account region
    start_time='2025-04-19T00:00:00+00:00',
    end_time='2025-04-19T23:59:59+00:00',
    query_string='fields @timestamp, @message | filter level = "ERROR" | stats count() by bin(5m)',
    account_label='prod-123456789012',  # Optional label for result annotation
    profile_name='prod-readonly'  # AWS profile with cross-account access
)

Performance tips:

• Use limit parameter or | limit N in query to control result size
• Narrow time ranges for faster queries
• The tool automatically splits time ranges if hitting 10,000-record limit
• Monitor summary.warnings for optimization suggestions

Common errors and solutions:

• Invalid ISO 8601 timestamp: Ensure timestamps include timezone (e.g., +00:00)
• start_time must be before end_time: Check time range order
• Query failed... bad query syntax: Verify query syntax at AWS Logs Insights docs
• Large result warnings: Add | limit N to query or use smaller time ranges

Required IAM Permissions

• cloudwatch:DescribeAlarms

• cloudwatch:DescribeAlarmHistory

• cloudwatch:GetMetricData

• cloudwatch:ListMetrics

• logs:DescribeLogGroups

• logs:DescribeQueryDefinitions

• logs:ListLogAnomalyDetectors

• logs:ListAnomalies

• logs:StartQuery

• logs:GetQueryResults

• logs:StopQuery

Installation

Option 1: Python (UVX)

Prerequisites

1. Install uv from Astral or the GitHub README
2. Install Python using uv python install 3.10

One Click Install

Kiro	Cursor	VS Code

MCP Config (Kiro, Cline)

• For Kiro, update MCP Config (~/.kiro/settings/mcp.json)
• For Cline click on "Configure MCP Servers" option from MCP tab

{
  "mcpServers": {
    "awslabs.cloudwatch-mcp-server": {
      "autoApprove": [],
      "disabled": false,
      "command": "uvx",
      "args": [
        "awslabs.cloudwatch-mcp-server@latest"
      ],
      "env": {
        "AWS_PROFILE": "[The AWS Profile Name to use for AWS access]",
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "transportType": "stdio"
    }
  }
}

Windows Installation

For Windows users, the MCP server configuration format is slightly different:

{
  "mcpServers": {
    "awslabs.cloudwatch-mcp-server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "awslabs.cloudwatch-mcp-server@latest",
        "awslabs.cloudwatch-mcp-server.exe"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR",
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

Please reference AWS documentation to create and manage your credentials profile

Option 2: Docker Image

Prerequisites

Build and install docker image locally on the same host of your LLM client

1. Install Docker
2. git clone https://github.com/awslabs/mcp.git
3. Go to sub-directory cd src/cloudwatch-mcp-server/
4. Run docker build -t awslabs/cloudwatch-mcp-server:latest .

One Click Cursor Install

MCP Config using Docker image(Kiro, Cline)

  {
    "mcpServers": {
      "awslabs.cloudwatch-mcp-server": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "--interactive",
          "-v",
          "~/.aws:/root/.aws",
          "-e",
          "AWS_PROFILE=[The AWS Profile Name to use for AWS access]",
          "awslabs/cloudwatch-mcp-server:latest"
        ],
        "env": {},
        "disabled": false,
        "autoApprove": []
      }
    }
  }

Please reference AWS documentation to create and manage your credentials profile

Skills

This MCP server includes reusable investigation skills that encode domain expertise into structured workflows for AI agents.

Skill	Description	Setup Guide
AgentCore Investigation	Investigate Bedrock AgentCore runtime sessions — resolve session/trace IDs, query OTEL spans, filter noise, build timelines	Kiro CLI setup

Skills provide pre-built investigation pipelines that agents can follow. They include the skill definition (SKILL.md), reference documentation, and MCP server configuration.

See the skills directory for details.

Contributing

Contributions are welcome! Please see the CONTRIBUTING.md in the monorepo root for guidelines.

Feedback and Issues

We value your feedback! Submit your feedback, feature requests and any bugs at GitHub issues with prefix cloudwatch-mcp-server in title.