CloudWatch MCP Server

一个自定义的 MCP 服务器，基于 FastMCP 构建，把 Amazon CloudWatch 的 Metrics、Logs Insights 和 Alarms 暴露为可供 AI 助手调用的工具。它设计为既可在本地运行用于开发，也可作为容器镜像部署到 AWS Lambda，并以 Lambda Function URL 作为访问入口。

已验证 fastmcp==3.4.7 和 boto3（使用 moto 模拟）可正常工作（下面列出的所有工具都已对模拟的 CloudWatch/Logs 调用测试过）。部署前，请在 requirements.txt 中固定你自己的 fastmcp 版本。如果离上次查看已经有一段时间，请对照 gofastmcp.com 重新过一遍本 README——FastMCP 的 API 多次调整过形态（见下文“关于 FastMCP 频繁变动的 API 的说明”一节）。

工具列表

所有工具都是只读的——它们都不能在 CloudWatch 中修改、删除或创建任何内容。除非有特定理由需要加入写入能力，否则请保持这种状态；一旦由 AI 模型来决定何时调用这些工具，最小权限原则就变得格外重要。

Related MCP server: cloudwatch-mcp

1. 先在本地运行

上文已给出的信息是最快、最安全的验证工具的方式——在讨论 AWS 部署之前，先用它来验证工具可用。

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

直接将 MCP 客户端（Claude Desktop、Claude Code 等）指向这个命令即可——如果使用 Claude Desktop，请把它加到其 MCP 配置中：

{
  "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" }
    }
  }
}

要在本地测试 HTTP 传输（也就是 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：服务器允许访问什么

本文件夹里的 iam-policy.json 是服务器所需的最小权限集合——CloudWatch 需要的 GetMetricData/ListMetrics/DescribeAlarms*，Logs Insights 需要的 DescribeLogGroups/StartQuery/GetQueryResults/StopQuery。除此之外，没有更多。把它附加到运行服务器的任何身份上：

• 本地运行： 把它附加到一个 IAM 用户/角色，并通过 AWS_PROFILE 使用该身份，或者把权限授予你的 SSO 角色。

• 在 Lambda 上运行： 把它附加到 Lambda 函数的执行角色（另外还需要标准的 AWSLambdaBasicExecutionRole，用于函数自身的日志记录）——千万不要在镜像中内置访问密钥。

3. 部署到 AWS Lambda

CloudWatch 自己给出的“在没有协议代码的情况下，把一个已有函数暴露为 MCP 工具”的推荐方案是 Amazon Bedrock AgentCore Gateway——如果以后可以接受完全托管的方式，值得一看。下面讲的是字面意义上的“我们完全掌控 MCP 服务器”的路径：利用 AWS Lambda Web Adapter 让这个 FastMCP 应用不做任何修改、直接在 Lambda 中运行。

构建并推送容器镜像

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

创建 Lambda 函数

1. 从你刚刚推送的容器镜像创建函数。

2. 内存：先设 512 MB；超时：30 秒对大多数指标/告警调用来说已经足够，如果 Logs Insights 查询比较大，可以提高到 60–120 秒（query_logs 的 max_wait_seconds 必须明显小于函数超时时间）。

3. 引用带第二步 IAM 策略的执行角色。

4. 如果启用带流式处理的 Function URL，请把调用模式设为 RESPONSE_STREAM（适配器需要这个来代理长响应）。

5. 创建 Function URL：

   • 认证类型：AWS_IAM（快速个人测试之外，不要 使用 NONE——那会让任何掌握这个 URL 的人都能访问你的 CloudWatch 数据）。

   • 你的 MCP 客户端必须能够用 SigV4 对这个 URL 签名才能调用；当前大多数 MCP 客户端并不原生支持 SigV4，所以实际上它通常要放在一组能够签名请求的组件之后，比如说你团队控制的内网网关/代理，或者在 Function URL 前面再接一个启用 IAM 认证的 API Gateway，而不是直接使用 Function URL 本身的 IAM 认证。

6. MCP 端点会是 https://<function-url>/mcp。

检查已部署的函数

运行一个普通请求：

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

接着再对这个待配置的 Function URL 发布一次真正的 MCP initialize 请求（带上 SigV4 签名，例如用 awscurl，或写一个小型签名请求脚本）——请求体与上面本地 curl 测试相同。

4. 已知的边界情况（请如实告诉团队）

• 冷启动耗时长：一个完整 HTTP 服务器（uvicorn + FastMCP）在 Lambda 冷启动时启动的时间，比典型的轻量 Lambda handler 更大——所以空闲后的第一次调用会有多秒延迟。如果这个问题影响你的场景，可以用预置并发来缓解。

• 没有服务端推送 / 没有长会话：stateless_http=True 意味着每次工具调用都是全新独立的请求——调用之间不会保留任何上下文，服务器也不能主动向客户端推送消息。因此设计工具时，要让每次调用自带它需要的一切信息（这个服务器已经是这样的——比如 query_logs 在一次调用内就携带完整的时间范围和查询字符串）。

• 认证问题由你负责：Function URL 的 IAM 认证（或者你放到它前面的那些东西）是“AI 助手”和“任何拿到 URL 的人”之间的唯一防线。只要这个函数有机会数据集完整关联到任何沙箱账号以外的资源，就不要再跳过认证，哪怕只是很初期的测试也不行。

• Logs Insights 查询是轮询式而非推送式：query_logs 会阻塞式轮询 get_query_results，最长持续到 max_wait_seconds。如果查询很大，这会占用 Lambda 超时预算——因此最好把查询限定在合理范围（用 limit、缩小时间窗口），而不是开放式查询。

5. 关于 FastMCP 变动的 API 的说明

FastMCP 的 HTTP/无状态 API 在历史上的多个版本里出现过多次变化（stateless_http 参数曾在不同版本中位于 FastMCP() 构造器和 mcp.run()/mcp.http_app() 之间转移）。server.py 中的代码是按照 fastmcp==3.4.7 验证的（使用 mcp.run(transport="http", stateless_http=True, ...)）。如果你升级版本后出现任何问题，请“只要看一眼 gofastmcp.com/deployment/http”——这是最可能不匹配本 README 的地方。