Amazon CloudWatch MCP server: 19 read-only tools

AWS Labs' local server for CloudWatch logs, metrics, PromQL and alarms. Log queries are billed by data scanned, and a failed query comes back empty.

Checked 6 October 2026 · from AWS Labs' repository, the PyPI package source and AWS documentation

One of 91 guides to monitoring and developer tools. Each covers what an AI coding agent can get out of the tool through MCP, the protocol that lets the agent query the tool directly.

What is the Amazon CloudWatch MCP server?

It is AWS's server for the Model Context Protocol, built for troubleshooting agents. A connected agent can find firing alarms, pull the metrics behind them and query the logs from the same window.

The 19 tools fall into four groups. Logs covers discovery, anomaly and pattern analysis, Logs Insights queries and field-index advice. Metrics covers data, metadata, trend analysis and recommended alarms.

PromQL queries metrics ingested over OTLP. Alarms reads active alarms and their history.

The README documents 17 of the tools. recommend_indexes_loggroup and recommend_indexes_account are registered in the source and missing from the README's tool list.

It runs locally over stdio, on the same host as the client. Traces, SLOs and Application Signals live in a separate AWS Labs package, awslabs.cloudwatch-applicationsignals-mcp-server.

It covers production telemetry in CloudWatch, plus agent sessions when those agents run on Bedrock AgentCore. Code review, CI and cost sit outside it.

For an agent, that means CloudWatch answers what fired, what the metric did and what the logs said, inside one AWS account at a time. It can trace an alarm to its log lines. To follow a request across services it needs the Application Signals server beside it.

What can an AI agent do with Amazon CloudWatch?

Start with get_active_alarms in each region you run. Alarm names and times then scope every later query, which keeps Logs Insights scans small.

Amazon CloudWatch MCP server limits: where answers come back incomplete

Two of these limits announce themselves in a field an agent may skip. The third is silent.

How to configure Amazon CloudWatch MCP for agents

1. 1

   Give it a read-only CloudWatch role

   The README lists 11 IAM actions, all describe, get, list and query calls. The index-recommender tools also call logs:DescribeQueries, logs:DescribeIndexPolicies and logs:DescribeAccountPolicies.

2. 2

   Name the region

   Each tool takes a region argument. Left empty, it uses AWS_REGION or the profile's region, and then us-east-1.

3. 3

   Prefer a profile over inline keys

   AWS_PROFILE keeps credentials in the SDK's own store. Each tool also accepts profile_name, so one server can reach several accounts.

4. 4

   Run 0.3.1 or later

   Releases 0.1.0 to 0.2.1 accepted any region string in the PromQL client. A prompt-injected value could send signed requests to another host.

Paste this into your agent’s instructions

A failed query and an empty one look alike, and each tool answers for one region. The block makes the agent say which it saw.

When you answer using CloudWatch MCP tools, state:
- The region, the account and the time window you queried.
- The status of every Logs Insights query. An empty result
  with status Error or Polling Timeout means the query did
  not finish. It does not mean zero matches.
- How many rows or alarms came back, and the limit you set.
When a query returns zero rows, say so and name the
constraints above.
Write your answer in ASD-STE100 Simplified Technical
English. Use short sentences with one idea in each.

Do you need the MCP server at all?

Often the AWS CLI is enough. aws logs start-query and aws cloudwatch get-metric-data use the same credentials, and a coding agent already knows them.

The server's advantage is shaping. It polls queries to completion, trims pattern results, batches log groups across regions and suggests time windows from alarm history.

AWS's managed AWS MCP Server is the other route. Its call_aws tool can run AWS API operations, CloudWatch's among them, under your IAM credentials with nothing to install.

Connect it for incident work on AWS. Use the CLI for a query you already know.

Amazon CloudWatch MCP server setup

The package runs with uvx and needs Python 3.10 or later. It uses ordinary AWS credentials: a profile the SDK can find, or a key pair, plus a region.

The README states the server runs only on the same host as the MCP client. AWS's managed AWS MCP Server is a separate, hosted route, generally available since 6 May 2026.

claude mcp add-json "cloudwatch" '{"command":"uvx",
  "args":["awslabs.cloudwatch-mcp-server@latest"],
  "env":{"AWS_PROFILE":"your-profile","AWS_REGION":"us-east-1"}}'

{"mcpServers":{"cloudwatch":{"command":"uvx",
  "args":["awslabs.cloudwatch-mcp-server@latest"],
  "env":{"AWS_PROFILE":"your-profile","AWS_REGION":"us-east-1"}}}}

[mcp_servers.cloudwatch]
command = "uvx"
args = ["awslabs.cloudwatch-mcp-server@latest"]
env = { AWS_PROFILE = "your-profile", AWS_REGION = "us-east-1" }

Every other client

Each block below is the configuration for one client, with the file path and the key that client expects.

{"mcpServers":{"cloudwatch":{"command":"uvx",
  "args":["awslabs.cloudwatch-mcp-server@latest"],
  "env":{"AWS_PROFILE":"your-profile","AWS_REGION":"us-east-1"}}}}

{"mcpServers":{"cloudwatch":{"command":"uvx",
  "args":["awslabs.cloudwatch-mcp-server@latest"],
  "env":{"AWS_PROFILE":"your-profile","AWS_REGION":"us-east-1"}}}}

{"servers":{"cloudwatch":{"command":"uvx",
  "args":["awslabs.cloudwatch-mcp-server@latest"],
  "env":{"AWS_PROFILE":"your-profile","AWS_REGION":"us-east-1"}}}}

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

docker build -t awslabs/cloudwatch-mcp-server:latest .
docker run --rm --interactive -v ~/.aws:/root/.aws \
  -e AWS_PROFILE=your-profile awslabs/cloudwatch-mcp-server:latest

AWS_REGION=us-east-1 \
AWS_ACCESS_KEY_ID=<key> AWS_SECRET_ACCESS_KEY=<secret> \
uvx awslabs.cloudwatch-mcp-server@latest

Read-only access, permissions and security

• Every tool reads

  The server calls describe, get, list and Logs Insights query APIs. It cannot create an alarm, change retention or delete a log group.

• Log lines carry whatever your services wrote

  Tokens, emails and request bodies in a log reach the model once a query returns them.

• Queries spend money

  Logs Insights bills by uncompressed data scanned, and an agent can start several queries in one turn.

• Update to 0.3.1 or later

  Releases 0.1.0 to 0.2.1 could send requests signed with the server's credentials to a host named in a prompt-injected region value.

• Prefer a profile to inline keys

  Credentials then stay in the AWS SDK's store, outside the MCP client's configuration file.

Troubleshooting

AccessDeniedException on a log query

The IAM identity lacks a CloudWatch Logs action. Queries need logs:StartQuery, logs:GetQueryResults and logs:StopQuery alongside the describe permissions.

Status "Polling Timeout" with an empty result

The query outlived the tool's wait, 30 seconds by default, and is still running in CloudWatch. Fetch it with get_logs_insight_query_results, or stop it with cancel_logs_insight_query.

Alarms or log groups you know exist are missing

The tool queried a different region. When the region argument is empty, it uses AWS_REGION, then the profile's region, then us-east-1.

PromQL returns nothing for AWS metrics

Vended AWS metrics reach PromQL only after OTel enrichment is on, through aws cloudwatch start-otel-enrichment. Use get_metric_data for classic namespaces such as AWS/EC2.

get_metric_metadata returns nothing

The metadata is a file shipped in the package, with 1,179 metrics across 38 namespaces. Custom metrics and unlisted namespaces have no entry.

Amazon CloudWatch MCP server: Reference

What engineers report

This server ships inside the awslabs monorepo, so the useful signals are packaging and release history.

Package facts from PyPI and repository facts from the GitHub API, both read 6 October 2026. Tool names come from the registrations in the 0.3.1 package.

Should you connect an agent to Amazon CloudWatch?

Yes. Best for incident investigation on AWS, with a read-only CloudWatch role and the region named in every request.

Strongest fit

Teams on AWS who want an agent to move from a firing alarm to its metrics and logs in one conversation.

Main advantage

Task-shaped tools: query polling, cross-region log batching and alarm history with suggested investigation windows.

Main weakness

Failed and timed-out log queries return empty results, and every log query is billed by data scanned.

Operational risk

Low for writes, because every tool reads. Query spend and log contents are the exposure.

Frequently asked questions