youweichen0208/mcp-ops-server

MCP OPS Server

企业云运维平台 MCP (Model Context Protocol) 服务器 - 通过 Claude Code 智能分析和管理云基础设施。

🌟 功能特性

核心功能

• 实例管理：查询、监控和分析云实例
• 智能分析：AI 驱动的健康度评估和优化建议
• 日志查询：快速搜索和分析实例日志
• 告警管理：查看和分析告警历史

技术亮点

• MCP 协议：标准化的 Claude 工具集成
• FastAPI：高性能异步 API 服务器
• Playwright 自动化：通过浏览器自动化获取数据（支持无 API 的场景）
• Redis 缓存：智能缓存减少请求次数
• Docker 部署：一键启动，开箱即用
• 企业级安全：Token 认证和 CORS 配置

📋 MCP 工具列表

实例管理（3个工具）

1. list_instances - 查询实例列表（支持过滤）
2. get_instance_detail - 获取实例详细信息
3. get_instance_status - 快速查询实例状态

监控分析（2个工具）

4. get_instance_metrics - 获取监控指标（CPU/内存/磁盘/网络）
5. analyze_instance_health - AI 智能健康度分析

日志查询（2个工具）

6. search_instance_logs - 搜索实例日志
7. get_error_logs - 快速获取错误日志

告警管理（1个工具）

8. get_alert_history - 查看告警历史

🚀 快速开始

1. 前置要求

• Docker 和 Docker Compose
• OPS 平台 Web 访问权限（用户名和密码）
• Claude Code CLI

2. 克隆项目

git clone <your-repo-url>
cd mcp-ops-server

3. 配置环境变量

# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件，配置 OPS 平台访问信息：
OPS_WEB_URL=https://ops.yourcompany.com
OPS_USERNAME=your_username
OPS_PASSWORD=your_password
OPS_HEADLESS=true  # true=后台运行，false=显示浏览器窗口（调试用）

# 其他配置
MCP_SERVER_TOKEN=your_mcp_server_token_here

4. 安装 Playwright 浏览器

# 在 Docker 环境中会自动安装
# 如果是本地开发，需要手动安装
playwright install chromium

5. 启动服务

# 使用快速启动脚本
./scripts/start.sh

# 或手动启动
cd docker
docker-compose up -d

5. 验证服务

# 运行测试脚本
./scripts/test.sh

# 或手动测试
curl http://localhost:8000/health

6. 配置 Claude Code

编辑 ~/.claude/config.json：

{
  "mcpServers": {
    "ops-platform": {
      "type": "http",
      "url": "http://localhost:8000",
      "headers": {
        "Authorization": "Bearer your-mcp-server-token"
      }
    }
  }
}

7. 开始使用

在 Claude Code 中测试：

# 启动 Claude Code
claude

# 在对话中使用
"列出所有运行中的实例"
"分析实例 i-12345678 的健康状况"
"查看实例 i-12345678 最近1小时的错误日志"

🏗️ 项目结构

mcp-ops-server/
├── src/
│   ├── main.py                 # FastAPI 应用入口
│   ├── mcp_server.py           # MCP Server 核心
│   ├── tools/                  # MCP 工具实现
│   │   ├── instance_tools.py   # 实例管理工具
│   │   ├── monitoring_tools.py # 监控分析工具
│   │   ├── log_tools.py        # 日志查询工具
│   │   └── alert_tools.py      # 告警管理工具
│   ├── clients/                # OPS 平台客户端
│   │   ├── ops_client.py       # OPS 客户端（基于 Playwright 浏览器自动化）
│   │   ├── ops_selectors.py    # 页面选择器配置
│   │   └── page_helpers.py     # 页面操作辅助函数
│   ├── models/                 # 数据模型
│   │   ├── instance.py         # 实例模型
│   │   └── response.py         # 响应模型
│   └── utils/                  # 工具函数
│       ├── logger.py           # 日志配置
│       └── cache.py            # 缓存管理
├── docker/
│   ├── Dockerfile              # Docker 镜像配置
│   └── docker-compose.yml      # 服务编排配置
├── config/
│   └── config.yaml             # 应用配置
├── scripts/
│   ├── start.sh                # 快速启动脚本
│   └── test.sh                 # 测试脚本
├── requirements.txt            # Python 依赖
├── .env.example                # 环境变量模板
└── README.md                   # 本文档

🔧 配置说明

环境变量

⚠️ 如果不设置 MCP_SERVER_TOKEN，将跳过认证检查（仅用于开发环境）

OPS 平台适配

项目使用 Playwright 浏览器自动化获取数据，需要根据实际 OPS 平台的页面结构进行适配：

配置步骤：

1. 配置 .env 中的 OPS_WEB_URL、OPS_USERNAME、OPS_PASSWORD
2. 根据实际 OPS 平台的 HTML 结构，调整 src/clients/ops_selectors.py 中的选择器：
   • 登录表单选择器（LOGIN_USERNAME、LOGIN_PASSWORD 等）
   • 数据列表选择器（INSTANCE_LIST_CONTAINER、INSTANCE_ROW 等）
   • 详情页选择器（INSTANCE_DETAIL_CONTAINER 等）

调试技巧：

• 设置 OPS_HEADLESS=false 可以看到浏览器操作过程
• 使用浏览器开发者工具查看元素选择器
• 查看日志了解 Playwright 执行步骤
• 使用 page_helpers.py 中的辅助函数简化页面操作

🔍 API 端点

健康检查

GET /health

MCP 工具列表

POST /mcp/tools/list
Headers: Authorization: Bearer <token>

MCP 工具调用

POST /mcp/tools/call
Headers: Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "list_instances",
  "arguments": {
    "status": "running",
    "page": 1,
    "page_size": 10
  }
}

服务统计

GET /stats
Headers: Authorization: Bearer <token>

📊 监控和日志

查看日志

# 实时日志
cd docker && docker-compose logs -f mcp-ops-server

# 查看最近100行
docker-compose logs --tail=100 mcp-ops-server

# 查看错误日志
docker-compose logs mcp-ops-server | grep ERROR

查看服务状态

# 查看所有容器状态
cd docker && docker-compose ps

# 查看资源使用
docker stats mcp-ops-server mcp-redis

重启服务

# 重启 MCP Server
cd docker && docker-compose restart mcp-ops-server

# 重启所有服务
docker-compose restart

# 重新构建并启动
docker-compose up -d --build

🛠️ 开发指南

本地开发环境

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt

# 安装 Playwright 浏览器
playwright install chromium

# 启动本地 Redis（可选）
docker run -d -p 6379:6379 redis:7-alpine

# 启动开发服务器
uvicorn src.main:app --reload --port 8000

添加新工具

1. 在 src/tools/ 下创建工具文件
2. 定义工具元数据（Tool 对象）
3. 实现工具处理函数
4. 在 src/tools/__init__.py 中注册工具
5. 在 src/mcp_server.py 中添加处理器映射

运行测试

# 运行所有测试
pytest

# 运行特定测试
pytest tests/test_tools.py

# 生成覆盖率报告
pytest --cov=src --cov-report=html

🐛 故障排查

服务无法启动

1. 检查 .env 文件是否正确配置
2. 确认 OPS API 地址可访问
3. 查看日志：docker-compose logs mcp-ops-server

OPS 平台访问失败

1. 检查用户名密码是否正确
2. 验证登录页面 URL 是否正确
3. 查看浏览器日志：设置 OPS_HEADLESS=false 观察登录过程
4. 检查 ops_selectors.py 中的登录表单选择器是否匹配
5. 查看应用日志获取详细错误信息

Claude Code 无法连接

1. 确认 MCP Server 正在运行：curl http://localhost:8000/health
2. 检查 ~/.claude/config.json 配置
3. 验证 MCP_SERVER_TOKEN 是否匹配
4. 重启 Claude Code

Redis 连接失败

服务会自动降级为无缓存模式，不影响核心功能。如需修复：

1. 确认 Redis 容器运行正常
2. 检查 REDIS_URL 配置
3. 查看 Redis 日志：docker-compose logs redis

📝 使用示例

示例 1：查询运行中的实例

Claude: 列出所有运行中的生产环境实例

MCP Server 会调用 list_instances 工具，返回格式化的实例列表。

示例 2：分析实例健康状况

Claude: 分析实例 i-12345678 的健康状况

MCP Server 会：
1. 获取实例信息
2. 获取最近6小时的监控数据
3. 进行智能分析
4. 给出健康评分和优化建议

示例 3：排查错误

Claude: 查看实例 i-12345678 最近1小时的错误日志

MCP Server 会搜索 ERROR 级别的日志并格式化展示。

🤝 贡献指南

欢迎贡献代码、报告问题或提出建议！

1. Fork 本仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m 'Add amazing feature'
4. 推送到分支：git push origin feature/amazing-feature
5. 提交 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 详见 文件

🙏 致谢

• Model Context Protocol (MCP)
• FastAPI
• Claude Code

📧 联系方式

如有问题或建议，请提交 Issue 或联系项目维护者。

Made with ❤️ for enterprise DevOps teams