MCP AWS Monitor

Logispot AWS 基础设施监控 MCP 服务器。

项目结构

mcp-aws-monitor/
├── .env                ← AWS 키 + Google OAuth 키 (git 미추적)
├── .env.example        ← .env 템플릿
├── .gitignore
├── pyproject.toml      ← 패키지 정의 (mcp, boto3, httpx, uvicorn 등)
├── README.md
└── src/
    ├── __init__.py
    ├── server.py       ← MCP 서버 진입점 (stdio / HTTP 모드)
    ├── google_oauth.py ← Google OAuth Provider (HTTP 모드용)
    ├── aws_client.py   ← boto3 클라이언트 팩토리 (lru_cache)
    ├── cloudwatch.py   ← CloudWatch 도구 4개
    ├── sqs.py          ← SQS 도구 3개
    ├── rds.py          ← RDS 도구 3개
    ├── s3.py           ← S3 도구 4개
    ├── ec2.py          ← EC2/ECS/AutoScaling 도구 5개
    ├── sns.py          ← SNS 도구 2개
    └── lambda_tools.py ← Lambda 도구 3개

Related MCP server: AWS SSO MCP Server

集成方式

可以通过两种方式与 Claude Code 集成。

方式 1：stdio（仅限本地）

Claude Code 将 MCP 服务器作为子进程直接运行的方式。 仅可在同一台机器上使用，无需额外认证。

Claude Code --stdio--> MCP 서버 (자식 프로세스)

运行方法：

1. 将 Claude Code 设置改为 stdio（参见下文）

2. 启动 Claude Code 后自动运行（无需单独启动服务器）

Claude Code 设置（~/.claude.json 或 ~/.claude/.mcp.json）：

{
  "mcpServers": {
    "aws-monitor": {
      "command": "/path/to/mcp-aws-monitor/.venv/bin/python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/mcp-aws-monitor"
    }
  }
}

注册 CLI：

claude mcp add aws-monitor -s user -- /path/to/mcp-aws-monitor/.venv/bin/python -m src.server

方式 2：HTTP + Google OAuth（远程/多用户）

将 MCP 服务器作为独立 HTTP 服务器运行，并通过 Google OAuth 进行认证的方式。 将服务器部署到 EC2 等环境后，团队成员可以共享使用。

Claude Code --HTTP--> MCP 서버 (:8000)
                        ↓ (인증 필요)
                      브라우저 → Google 로그인
                        ↓ (로그인 완료)
                      /google/callback → MCP 토큰 발급
                        ↓
                      Claude Code가 토큰으로 MCP 도구 사용

准备工作：

1. 在 Google Cloud Console 中创建 OAuth 客户端

   • API 和服务 → OAuth 同意屏幕 → 用户类型：内部（仅限 Workspace 组织）

   • 凭据 → OAuth 客户端 ID → Web 应用程序

   • 授权重定向 URI：http://{服务器地址}:8000/google/callback

2. 添加至 .env：

   GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com
   GOOGLE_CLIENT_SECRET=GOCSPX-xxx
   MCP_SERVER_URL=http://localhost:8000   # 배포 시 실제 서버 URL로 변경

运行方法：

1. 将 Claude Code 设置改为 http（参见下文）

2. 直接运行 MCP 服务器：

   cd /path/to/mcp-aws-monitor
   .venv/bin/python -m src.server --http
   # Uvicorn running on http://0.0.0.0:8000

3. 启动（或重启）Claude Code

4. 调用 MCP 工具时，浏览器将自动打开，完成 Google 登录后自动认证

服务器终止：Ctrl+C

Claude Code 设置（~/.claude.json 或 ~/.claude/.mcp.json）：

{
  "mcpServers": {
    "aws-monitor": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

注册 CLI：

claude mcp add --transport http -s user aws-monitor http://localhost:8000/mcp

注意事项：

• 将 Google OAuth 同意屏幕设置为"内部"时，仅同一 Google Workspace 组织内的账号可访问

• 令牌为内存存储，因此服务器重启时需要重新登录

• localhost 仅限本机访问。团队共享时需要部署服务器

架构

运行流程（stdio）

Claude Code 세션 시작
  → MCP 서버 프로세스 실행 (src/server.py)
    → .env에서 AWS 키 로드 (python-dotenv)
    → FastMCP 인스턴스 생성
    → 각 모듈의 register_tools()로 도구 24개 등록
    → stdio 기반으로 Claude Code와 통신

运行流程（HTTP + Google OAuth）

MCP 서버 실행 (uvicorn :8000)
  → .env에서 AWS 키 + Google OAuth 키 로드
  → FastMCP 인스턴스 생성 (AuthSettings 포함)
  → OAuth 엔드포인트 자동 마운트 (/authorize, /token, /register, /revoke)
  → /google/callback 라우트 추가
  → /mcp 엔드포인트에서 인증된 요청만 도구 실행

aws_client.py

使用 lru_cache 缓存 boto3 客户端的工厂。 同一服务仅创建一次客户端并重复使用。 所有模块通过 get_client("服务名") 调用。

模块模式

所有工具遵循相同的模式：

1. 通过 get_client() 获取 boto3 客户端

2. 调用 AWS API

3. 将响应转换为韩语格式字符串并返回

由于 MCP 工具的返回值必须是字符串，因此均使用 -> str。

提供的工具（24 个）

CloudWatch（4 个）

cloudwatch_get_alarms

查询 CloudWatch 告警状态。

• state_filter（str，默认 "ALL"）：ALARM、OK、INSUFFICIENT_DATA、ALL

• 同时查询 MetricAlarms 和 CompositeAlarms

• 返回告警名称、关联指标、状态变更原因

cloudwatch_get_metric

查询特定指标的时间序列数据。

• namespace（str）：AWS 命名空间（例如：AWS/EC2、AWS/RDS）

• metric_name（str）：指标名称（例如：CPUUtilization）

• dimension_name（str）：维度名称（例如：InstanceId）

• dimension_value（str）：维度值（例如：i-0abc123）

• stat（str，默认 "Average"）：Average、Sum、Maximum、Minimum、SampleCount

• hours（int，默认 1）：查询时间范围

• Period 自动计算，最小 5 分钟，最多 60 个数据点

cloudwatch_search_logs

执行 CloudWatch Logs Insights 查询。

• log_group（str）：日志组名称（例如：/ecs/logispot-api）

• query（str）：Insights 查询语句

• hours（int，默认 1）：查询时间范围

• limit（int，默认 50）：结果数量限制

• 异步查询 → 最多等待 30 秒，每秒轮询一次以等待完成

• 如果查询中未包含 limit 子句，将自动添加

cloudwatch_list_log_groups

查询 CloudWatch 日志组列表。

• prefix（str，可选）：日志组名称前缀筛选

• 使用分页器查询全部列表

• 显示每个日志组的存储大小（MB）

SQS（3 个）

sqs_list_queues

查询 SQS 队列列表和消息数量。

• prefix（str，可选）：队列名称前缀筛选

• 按队列显示等待中（Visible）/处理中（NotVisible）/延迟（Delayed）的消息数量

sqs_queue_detail

查询 SQS 队列详细信息。

• queue_name（str）：队列名称

• 显示 ARN、消息数量、VisibilityTimeout、MessageRetentionPeriod

• 如果包含 RedrivePolicy，则解析并显示 DLQ 名称和 maxReceiveCount

sqs_peek_messages

预览 SQS 队列中的消息。不删除消息。

• queue_name（str）：队列名称

• count（int，默认 5）：查询数量（最多 10 个）

• 使用 VisibilityTimeout=0 调用，使消息立即可见

• 显示消息 Body 最多 500 个字符

RDS（3 个）

rds_list_instances

查询 RDS 实例列表及状态。

• 无参数

• 按实例显示标识符、状态、引擎/版本、实例类型、存储、Multi-AZ、端点

rds_get_metrics

查询 RDS 实例关键指标。使用 CloudWatch API。

• db_instance_id（str）：RDS 实例标识符

• hours（int，默认 1）：查询时间范围

• 查询 7 个指标：

  • CPUUtilization（%）

  • DatabaseConnections（个）

  • FreeStorageSpace（转换为 GB）

  • ReadLatency / WriteLatency（秒）

  • ReadIOPS / WriteIOPS

• 返回每个指标的最新数据点值

rds_slow_queries

通过 RDS Performance Insights 查询 Top N 慢查询。

• db_instance_id（str）：RDS 实例标识符

• hours（int，默认 1）：查询时间范围

• limit（int，默认 10）：结果数量

• 通过 RDS API 查询 DbiResourceId → 通过 PI API 基于 db.load.avg 查询排序

• 对已禁用 Performance Insights 的实例返回空结果

S3（4 个）

s3_list_buckets

查询 S3 存储桶列表。

• 无参数

• 显示存储桶名称、创建日期

s3_list_objects

查询 S3 存储桶内的对象列表。

• bucket（str）：存储桶名称

• prefix（str，可选）：路径前缀（例如：logs/2024/）

• limit（int，默认 30）：结果数量

• 先通过 MaxKeys 截取，再按 LastModified 逆序排序

• 文件大小自动转换为 KB/MB

s3_get_bucket_size

计算 S3 存储桶或前缀的总大小。

• bucket（str）：存储桶名称

• prefix（str，可选）：路径前缀

• 使用分页器遍历所有对象并累加

• 返回文件数量、总大小（自动转换为 KB/MB/GB）

• 大容量存储桶可能需要较长时间

s3_read_text_file

读取 S3 文本文件内容。

• bucket（str）：存储桶名称

• key（str）：文件键

• max_bytes（int，默认 10000）：最大读取字节数

• 使用 Range 头读取文件开头部分（安全处理大文件）

• UTF-8 解码，乱码字符按 replace 处理

EC2 / ECS / AutoScaling（5 个）

ec2_list_instances

查询 EC2 实例列表。

• state_filter（str，默认 "running"）：running、stopped、all

• 显示 Name 标签、实例 ID、类型、状态、可用区、私有/公有 IP

ec2_get_cpu

查询 EC2 实例 CPU 使用率时间序列。

• instance_id（str）：EC2 实例 ID

• hours（int，默认 1）：查询时间

• 同时显示 Average 和 Maximum 两个统计值

ecs_list_clusters

查询 ECS 集群列表。

• 无参数

• 按集群显示状态、活跃服务数量、运行中/待处理任务数量

ecs_list_services

查询 ECS 集群内服务列表及状态。

• cluster（str）：集群名称或 ARN

• 按服务显示状态、Desired/Running/Pending 计数、任务定义

autoscaling_list_groups

查询 Auto Scaling 组列表及现状。

• 无参数

• 按组显示实例数量、Min/Max/Desired 设置、健康检查类型

SNS（2 个）

sns_list_topics

查询 SNS 主题列表。

• 无参数

• 显示主题名称、ARN

sns_get_topic_subscriptions

查询 SNS 主题的订阅列表。

• topic_arn（str）：主题 ARN（例如：arn:aws:sns:ap-northeast-2:123456:my-topic）

• 按订阅显示协议、端点、SubscriptionArn

Lambda（3 个）

lambda_list_functions

查询 Lambda 函数列表。

• 无参数

• 显示函数名、运行时、描述、最后修改时间

lambda_get_function

查询 Lambda 函数详细信息。

• function_name（str）：函数名称或 ARN

• 显示配置信息（运行时、处理程序、内存、超时时间）、环境变量键、事件源映射、资源策略

lambda_get_code

查询 Lambda 函数源代码。

• function_name（str）：函数名称或 ARN

• 下载部署包并显示源文件（.py、.js、.ts、.json 等）的内容

• 排除 node_modules、pycache 等依赖目录

安装

cd ~/work/mcp-aws-monitor
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

设置

在 .env 文件中输入所需密钥：

# AWS (필수)
AWS_ACCESS_KEY_ID=your-key
AWS_SECRET_ACCESS_KEY=your-secret
AWS_DEFAULT_REGION=ap-northeast-2

# Google OAuth (HTTP 모드 사용 시)
GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxx
MCP_SERVER_URL=http://localhost:8000

Claude Code 的集成方式请参见上方集成方式章节。

IAM 权限

创建 IAM 用户时关联以下内联策略：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "cloudwatch:Describe*",
        "cloudwatch:Get*",
        "logs:Describe*",
        "logs:StartQuery",
        "logs:GetQueryResults",
        "sqs:List*",
        "sqs:Get*",
        "sqs:ReceiveMessage",
        "rds:Describe*",
        "pi:Describe*",
        "s3:List*",
        "s3:Get*",
        "ec2:Describe*",
        "ecs:List*",
        "ecs:Describe*",
        "autoscaling:Describe*",
        "lambda:List*",
        "lambda:Get*",
        "lambda:GetPolicy",
        "sns:List*",
        "sns:Get*"
      ],
      "Resource": "*"
    }
  ]
}

1. AWS 控制台 → IAM → 用户 → 创建用户

2. 权限设置 → "直接关联策略" → 在 JSON 选项卡中粘贴上述策略

3. 创建用户完成后颁发访问密钥（用于 CLI）

4. 在 .env 中输入密钥

已知限制

• 仅支持单区域（ap-northeast-2）。无法查询多区域

• 查询 EC2、RDS、AutoScaling 列表时仅返回第一页（大量资源时会被截断）

• s3_list_objects 先应用 S3 默认排序再应用 limit，因此可能不是真正的最近 N 个

• 如果 cloudwatch_search_logs 查询未在 30 秒内完成，可能返回不完整的结果

• AWS API 错误时异常会直接暴露（权限不足、资源 ID 错误等）