Registry /
aws / awslabs-cloudwatch-mcp-server
Install & Compatibility
Where this runs
tested against v0.1.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✕ build_error
452MB installed
● package 452MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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.")
awslabs-cloudwatch-mcp-server --version
Debug
Known issues
deprecatedThe `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.fixMigrate to `awslabs.cloudwatch-appsignals-mcp-server`. Refer to its documentation for configuration and usage.
affects: 0.0.24 and earlier
breakingServer 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.fixUpdate LLM clients or custom integrations to use the new transport capabilities (Streamable HTTP is planned) and no longer rely on SSE.
affects: Major versions released after May 26th, 2025
gotchaThis 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.fixEnsure 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.
affects: All
Errors
Common errors & fixes
error: Failed to spawn: `awslabs.cloudwatch-mcp-server` Caused by: program not found
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.
fixEnsure `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.
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.
fixCheck 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
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.
fixConsult 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.
Upgrade
Version history
0.1.4latest on PyPI · released May 20, 2026
Audit
Dependencies
uvoptionalRecommended tool for running MCP servers via `uvx`.
Python >=3.10requiredRuntime requirement for the server.
AWS credentialsrequiredRequired for accessing AWS services like CloudWatch.
Resources
No resource links recorded.