CloudWatch MCP Server

カスタムの MCP サーバーです。FastMCP で構築しており、Amazon CloudWatch のメトリクス、Logs Insights、アラームを、AI アシスタントが呼び出せるツールとして公開します。開発用にはローカルで実行し、AWS 上ではコンテナイメージとして AWS Lambda にデプロイして、Lambda Function URL を前面に配置する設計です。

fastmcp==3.4.7 と boto3 を、moto モックに対してテストしています(後述のすべてのツールを、モック化した CloudWatch/Logs 呼び出しに対して検証済みです)。デプロイ前に、名前を固定した fastmcp のバージョンを requirements.txt で宣言してください。また、しばらく時間が経っている場合は、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 だけです。それ以外は不要で、何も持たせません。サーバーを走らせる ID であれば、何にでもこのポリシーをアタッチしてください。

• ローカル: IAM ユーザー / ロールにアタッチし、AWS_PROFILE 経由でその権限を使うか、SSO ロールに権限を付与してください。

• Lambda 上: その Lambda 関数の実行ロール にアタッチしてください(関数自身のログ出力のために標準の AWSLambdaBasicExecutionRole も同様にアタッチします)。アクセスキーをコンテナイメージに埋め込んでしまわないでください。

3. AWS Lambda へのデプロイ

「プロトコルを書き込まずに既存の関数を MCP ツールとして公開する」方法として、CloudWatch 自身が推奨するのは 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. 手順 2 の IAM ポリシーを付けた実行ロールをアタッチします。

4. ストリーミング対応の Function URL を使う場合は、Invoke mode を RESPONSE_STREAM に設定します(長い応答をアダプターが仲介するために必要です)。

5. Function URL を作成します。

   • 認証タイプは AWS_IAM にします(単発の個人的なテスト以外で NONE を使わないでください。URL を知る人なら誰でも CloudWatch データに取得できてしまい)。

   • この URL を呼び出すには、MCP クライアントが SigV4 でリクエストに署名する必要があります。まだ最もな MCP クライアントはそれを nativにサポートしていないので、パターンして署名できるものの後段に置いて使います。例: チームが管理する内部ゲートウェイ / プロキシ、または AgentCore Function URL の IAM 認証を直接使うのではなく、その手前に IAM 認証の付いた API Gateway を置いて使います。

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 テストと同じ JSON です。

4. 既知の粗い部分(チームには包み隠さず伝えること)

• コールドスタート: 完全版の HTTP サーバー(uvicorn + FastMCP)を Lambda コールドスタートで起動するの遅く、軽量な一般的な Lambda ハンドラよりは遅くなります。アイドル後の呼び出しには数秒の待ち時間があると思ってください。業務に影響するなら Provisioned State で緩和できます。

• サーバープッシュなし / 長く生きているセッションなし:stateless_http=True の場合、1 回のツール呼び出しが新しい自己完結したリクエストになります。呼び出し間で何も記憶を持ち越さず、サーバからクライアントへプロアクティブにメッセージを送ることもできません。各ツールは、一回の呼び出しに必要なものを全て渡すように設計してください(このサーバ自身はすでにそうなっていることを満たしています。例: query_logs は全時間帯とクエリ文字をを見せてもうワンコールで受け取る)

• 認証は自分持ち: Function URL の IAM 認証(またはその前段に置く物)だけが「AI アシスタント」と「URL を知る人」の間に1枚の壁です。使い捨てサンドボックスアカウント以上の物に触れるなら、そこに使っていない、早い段階のテスト中でもスキップしないでください。

• Logs Insights クエリはプッシュではなくポーリングです: query_logs は停止して、最大 max_wait_seconds の間 get_query_results をポーリングします。非常に大きなクエリは 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を疑ってください。最も変わっている可能性が高いのがそこです。