AWS Labs CloudWatch MCP Server

0.0.24 · deprecated · verified Thu Apr 16

The `awslabs-cloudwatch-mcp-server` is an AWS Labs Model Context Protocol (MCP) server designed to provide AI assistants with comprehensive tools for monitoring, analyzing, and troubleshooting AWS services through CloudWatch. It enables AI agents to perform root cause analysis, investigate performance metrics, and track SLO compliance using natural language queries, eliminating the need for custom API integrations. The current version is 0.0.24, and its release cadence is tied to updates within the broader AWS Labs MCP ecosystem. As of early 2026, it is marked as deprecated in favor of `cloudwatch-applicationsignals-mcp-server` for new implementations.

Common errors

```
error: Failed to spawn: `awslabs.cloudwatch-mcp-server` Caused by: program not found
```
cause The `uvx` command or the specified server executable is not found in the system's PATH or within the configured environment of the LLM client. This often happens when `uv` (and thus `uvx`) is not installed or the server path in `mcp.json` is incorrect.

fix Ensure `uv` is installed (`pip install uv`) and the path to `awslabs.cloudwatch-mcp-server.exe` (when using `uvx tool run`) or the Docker command is correctly specified in the LLM client's `mcp.json` configuration.
```
Server exited before responding to `initialize` request.
```
cause The MCP server failed to start correctly, often due to misconfiguration, missing dependencies, or issues with AWS credentials, preventing it from initializing communication with the LLM client.

fix Check the server's log output (e.g., by setting `FASTMCP_LOG_LEVEL` to `INFO` or `DEBUG` in the `mcp.json` env) for more specific errors. Verify AWS credentials, region, and profile are correctly set in the `env` section of `mcp.json`.
```
ValidationException when group_by is specified
```
cause Specific queries or tool usages within the MCP server might hit underlying AWS API limitations or require a different input format than provided, leading to a `ValidationException` from the AWS API.

fix Consult the specific tool's documentation or examples (e.g., for `billing-cost-management-mcp-server` which had a similar issue) to ensure the query parameters, especially for `group_by` or filters, adhere to the expected format and limitations of the underlying CloudWatch or related AWS APIs.

Warnings

deprecated The `awslabs-cloudwatch-mcp-server` is officially deprecated. Users are strongly advised to use `awslabs.cloudwatch-appsignals-mcp-server` for new deployments, as it offers enhanced capabilities for monitoring and analyzing AWS services using AWS Application Signals.
Fix: Migrate to `awslabs.cloudwatch-appsignals-mcp-server`. Refer to its documentation for configuration and usage.
breaking Server Sent Events (SSE) support was removed from all AWS MCP servers in their latest major versions on May 26th, 2025. This may affect clients expecting SSE for streaming updates.
Fix: Update LLM clients or custom integrations to use the new transport capabilities (Streamable HTTP is planned) and no longer rely on SSE.
gotcha This MCP server requires appropriate AWS IAM permissions to interact with CloudWatch. Lack of necessary permissions will result in tools failing to execute or returning incomplete data.
Fix: Ensure the AWS profile or environment variables used by the MCP server have sufficient IAM permissions for `logs:Describe*`, `logs:Get*`, `logs:List*`, `logs:StartQuery`, `logs:StopQuery`, and other CloudWatch actions relevant to the tools being used.

Install

pip install awslabs-cloudwatch-mcp-server Basic Installation (for Python environment, though typically run via uvx or Docker)
git clone https://github.com/awslabs/mcp.git cd mcp/src/cloudwatch-mcp-server/ docker build -t awslabs/cloudwatch-mcp-server:latest . Install via Docker (Recommended for LLM client integration)

Imports

awslabs.cloudwatch-mcp-server
```
{ "mcpServers": { "awslabs.cloudwatch-mcp-server": { "command": "uvx", "args": ["awslabs.cloudwatch-mcp-server@latest"] ... } } }
```
This is an MCP server, not a traditional Python library for direct import into application code. It's configured within an LLM client's settings (e.g., mcp.json) which then executes the server.

Quickstart

The `awslabs-cloudwatch-mcp-server` is designed to be consumed by AI assistants (LLM clients) rather than directly imported into Python applications. This quickstart demonstrates how to configure an LLM client (like Amazon Q or Claude Code) to use the server by defining its command and environment variables within the client's `mcp.json` configuration. Ensure AWS credentials and Docker (or `uvx`) are set up as prerequisites.

# 1. Ensure Docker is installed and AWS credentials are configured (e.g., via ~/.aws/credentials or env vars)
#    export AWS_PROFILE="your-aws-profile"
#    export AWS_REGION="us-east-1"

# 2. Build the Docker image (if not already done via install instructions)
#    git clone https://github.com/awslabs/mcp.git
#    cd mcp/src/cloudwatch-mcp-server/
#    docker build -t awslabs/cloudwatch-mcp-server:latest .

# 3. Configure your LLM client (e.g., Amazon Q CLI, Claude Code) with the following in its mcp.json config:
#    For Amazon Q CLI (e.g., ~/.aws/amazonq/mcp.json) or similar:
import os

mcp_config = {
  "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": os.environ.get('AWS_PROFILE', 'your-aws-profile'),
        "AWS_REGION": os.environ.get('AWS_REGION', 'us-east-1')
      }
    }
  }
}

# In a real scenario, this 'mcp_config' would be written to a JSON file
# and picked up by the LLM client. For example, if you were setting
# up Amazon Q CLI:
# import json
# with open(os.path.expanduser('~/.aws/amazonq/mcp.json'), 'w') as f:
#     json.dump(mcp_config, f, indent=2)

print("MCP server configuration snippet generated. Place this in your LLM client's mcp.json file.")

view raw JSON →