CloudWatch MCP Server

A custom MCP server, built with FastMCP, that exposes Amazon CloudWatch Metrics, Logs Insights, and Alarms as tools an AI assistant can call. Designed to run locally for development and to deploy onto AWS Lambda as a container image, fronted by a Lambda Function URL.

Tested against fastmcp==3.4.7 and boto3 with moto mocks (all tools listed below were exercised against mocked CloudWatch/Logs calls). Pin your own fastmcp version in requirements.txt before deploying, and re-check this README against gofastmcp.com if it's been a while — FastMCP's API has changed shape more than once (see the "A note on FastMCP's moving API" section below).

Tools exposed

Tool	What it does
list_metrics	Discover available metrics by namespace/name/dimension
get_metric_data	Fetch time-series data points for one metric
list_log_groups	List CloudWatch Log Groups, optionally by prefix
query_logs	Run a Logs Insights query and wait for results
list_alarms	List alarms, optionally filtered by state
get_alarm_history	Get state-change history for one alarm

All tools are read-only — none of them can modify, delete, or create anything in CloudWatch. Keep it that way unless there's a specific reason to add write access; least privilege matters a lot more once an AI model is the one deciding when to call these.

1. Run it locally first

This is the fastest way to prove the tools work before touching AWS deployment at all.

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Uses your normal AWS credentials (aws configure / AWS_PROFILE / SSO)
export AWS_PROFILE=your-profile
export AWS_REGION=us-east-1

python3 server.py   # defaults to stdio transport

Point an MCP client (Claude Desktop, Claude Code, etc.) at this command directly — for Claude Desktop, add to its MCP config:

{
  "mcpServers": {
    "cloudwatch": {
      "command": "/full/path/to/.venv/bin/python3",
      "args": ["/full/path/to/server.py"],
      "env": { "AWS_PROFILE": "your-profile", "AWS_REGION": "us-east-1" }
    }
  }
}

To test the HTTP transport locally (the mode used on Lambda):

MCP_TRANSPORT=http PORT=8080 python3 server.py
# then, from another terminal:
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

2. IAM: what the server is allowed to touch

iam-policy.json in this folder is the minimum permission set the server needs — GetMetricData/ListMetrics/DescribeAlarms* for CloudWatch, DescribeLogGroups/StartQuery/GetQueryResults/StopQuery for Logs Insights. Nothing else. Attach it to whatever identity runs the server:

• Locally: attach it to an IAM user/role and use that via AWS_PROFILE, or grant it to your SSO role.
• On Lambda: attach it to the Lambda function's execution role (plus the standard AWSLambdaBasicExecutionRole for the function's own logging) — never bake access keys into the image.

3. Deploying to AWS Lambda

CloudWatch's own recommended path for "expose an existing function as an MCP tool with no protocol code" is Amazon Bedrock AgentCore Gateway — worth a look if a fully managed option becomes acceptable later. What's below is the literal "we own the MCP server" path, using the AWS Lambda Web Adapter to let this exact FastMCP app run inside Lambda unmodified.

Build and push the container image

aws ecr create-repository --repository-name cloudwatch-mcp-server

aws ecr get-login-password --region <region> | \
  docker login --username AWS --password-stdin <account-id>.dkr.ecr.<region>.amazonaws.com

docker build -t cloudwatch-mcp-server .
docker tag cloudwatch-mcp-server:latest \
  <account-id>.dkr.ecr.<region>.amazonaws.com/cloudwatch-mcp-server:latest
docker push <account-id>.dkr.ecr.<region>.amazonaws.com/cloudwatch-mcp-server:latest

Create the Lambda function

1. Create the function from the container image you just pushed.
2. Memory: start at 512 MB; timeout: 30s is enough for most metric/alarm calls, bump to 60–120s if your Logs Insights queries are large (query_logs's max_wait_seconds should stay comfortably under the function timeout).
3. Attach the execution role with the IAM policy from step 2.
4. Set Invoke mode to RESPONSE_STREAM if you enable a Function URL with streaming (needed for the adapter to proxy long responses).
5. Create a Function URL:
   • Auth type: AWS_IAM (do not use NONE outside of a quick personal test — that leaves your CloudWatch data reachable by anyone with the URL).
   • Your MCP client will need to sign requests with SigV4 to call it; most MCP clients don't do this natively yet, so in practice this usually sits behind something that can sign requests — e.g. an internal gateway/proxy your team controls, or API Gateway with IAM auth in front of the Function URL instead of using the Function URL's own IAM auth directly.
6. The MCP endpoint will be https://<function-url>/mcp.

Sanity-check the deployed function

aws lambda invoke --function-name cloudwatch-mcp-server \
  --payload '{}' /tmp/out.json && cat /tmp/out.json

and then a real MCP initialize call against the Function URL (with SigV4 signing, e.g. via awscurl or a small signed-request script) — the same JSON body as the local curl test above.

4. Known rough edges (be honest with your team about these)

• Cold starts: a full HTTP server (uvicorn + FastMCP) booting inside a Lambda cold start is slower than a typical lightweight Lambda handler — expect multi-second latency on the first call after idle. Provisioned concurrency mitigates this if it matters for your use case.
• No server push / no long-lived session: stateless_http=True means every tool call is a fresh, self-contained request — nothing is remembered between calls, and the server can't proactively push messages to the client. Design tools so each call carries everything it needs (this server already does — e.g. query_logs takes the full time range and query string in one call).
• Auth is on you: the Function URL's IAM auth (or whatever you put in front of it) is the only thing standing between "AI assistant" and "anyone with the URL." Don't skip it, even in early testing, if the function ever touches anything beyond a disposable sandbox account.
• Logs Insights queries are polled, not pushed: query_logs blocks and polls get_query_results for up to max_wait_seconds. For very large queries this can eat into the Lambda timeout — keep queries scoped (limit, tight time ranges) rather than open-ended.

5. A note on FastMCP's moving API

FastMCP has changed its HTTP/stateless API more than once across versions (the stateless_http flag has moved between the FastMCP() constructor and mcp.run()/mcp.http_app() in different releases). The code in server.py was verified against fastmcp==3.4.7 (mcp.run(transport="http", stateless_http=True, ...)). If you bump the version and something breaks, check gofastmcp.com/deployment/http first — this is the most likely thing to have shifted.