pcp-mcp

🚀 pcp-mcp

pcp-mcp 是一个用于 性能协同监控平台 (Performance Co-Pilot, PCP) 指标的 MCP 服务器。它允许用户通过模型上下文协议查询系统性能指标，涵盖 CPU、内存、磁盘 I/O、网络、进程等多个方面。

📖 完整文档 | 🚀 快速开始

🚀 快速开始（无需安装）

使用 uvx 可立即运行，无需安装：

uvx pcp-mcp

或者将其作为全局工具持久安装：

uvx tool install pcp-mcp
pcp-mcp

📦 安装指南

使用 pip 安装：

pip install pcp-mcp

或者使用 uv 安装：

uv add pcp-mcp

📋 安装要求

• Python：3.10 及以上版本
• PCP：需运行 pmcd 和 pmproxy 的性能协同监控平台

# Fedora/RHEL/CentOS
sudo dnf install pcp
sudo systemctl enable --now pmcd pmproxy

# Ubuntu/Debian
sudo apt install pcp
sudo systemctl enable --now pmcd pmproxy

⚙️ 配置说明

通过环境变量进行配置：

| 变量 | 描述 | 默认值 | |------|------|---------| | PCP_HOST | pmproxy 主机 | localhost | | PCP_PORT | pmproxy 端口 | 44322 | | PCP_TARGET_HOST | 要监控的目标 pmcd 主机 | localhost | | PCP_USE_TLS | 是否对 pmproxy 使用 HTTPS | false | | PCP_TLS_VERIFY | 是否验证 TLS 证书 | true | | PCP_TLS_CA_BUNDLE | 自定义 CA 证书包路径 | （可选） | | PCP_TIMEOUT | 请求超时时间（秒） | 30 | | PCP_USERNAME | HTTP 基本认证用户名 | （可选） | | PCP_PASSWORD | HTTP 基本认证密码 | （可选） | | PCP_ALLOWED_HOSTS | 通过主机参数允许的主机规格 | （可选） |

💻 使用示例

监控本地主机（默认）

pcp-mcp

监控远程主机

PCP_TARGET_HOST=webserver1.example.com pcp-mcp

或者使用 CLI 标志：

pcp-mcp --target-host webserver1.example.com

连接到远程 pmproxy

PCP_HOST=metrics.example.com pcp-mcp

使用 SSE 传输

pcp-mcp --transport sse

🔌 MCP 客户端配置

Claude Desktop

添加到 ~/.config/claude/claude_desktop_config.json：

{
  "mcpServers": {
    "pcp": {
      "command": "uvx",
      "args": ["pcp-mcp"]
    }
  }
}

用于远程监控：

{
  "mcpServers": {
    "pcp": {
      "command": "uvx",
      "args": ["pcp-mcp", "--target-host", "webserver1.example.com"]
    }
  }
}

💡 使用 uvx 意味着你无需安装 pcp-mcp，它可以直接从 PyPI 运行。

🛠️ 可用工具

系统监控

• get_system_snapshot - 获取系统的即时概况（CPU、内存、磁盘、网络、负载）
• get_process_top - 按 CPU、内存或 I/O 使用情况列出顶级进程
• query_metrics - 获取特定 PCP 指标的当前值
• search_metrics - 按名称模式发现可用指标
• describe_metric - 获取指标的详细元数据

查询示例

"当前 CPU 使用率是多少？"
→ 使用 get_system_snapshot

"显示按内存使用情况排名前 10 的进程"
→ 使用 get_process_top(sort_by="memory", limit=10)

"网络流量有哪些可用指标？"
→ 使用 search_metrics(pattern="network")

"获取 kernel.all.load 的详细信息"
→ 使用 describe_metric(name="kernel.all.load")

💡 使用场景

性能故障排除

向 Claude 询问：

• "分析当前系统性能并找出瓶颈"
• "为什么我的磁盘 I/O 这么高？"
• "哪些进程占用了最多的 CPU？"

系统监控

• "对生产服务器进行健康检查"
• "比较过去一分钟的 CPU 使用率"
• "监控 eth0 上的网络流量"

容量规划

• "内存利用率趋势如何？"
• "显示所有文件系统的磁盘使用情况"
• "分析进程资源消耗模式"

🏗️ 架构说明

┌─────────┐         ┌─────────┐          ┌─────────┐         ┌─────────┐
│   LLM   │ ◄─MCP─► │ pcp-mcp │ ◄─HTTP─► │ pmproxy │ ◄─────► │  pmcd   │
└─────────┘         └─────────┘          └─────────┘         └─────────┘
                                         (REST API)          (metrics)

• pcp-mcp：通过 MCP 工具公开 PCP 指标的 FastMCP 服务器
• pmproxy：PCP 的 REST API 服务器（默认运行在端口 44322）
• pmcd：PCP 指标收集守护进程
• 远程监控：设置 PCP_TARGET_HOST 可通过 pmproxy 查询不同的 pmcd 实例

🔧 开发指南

# 安装依赖
uv sync --dev

# 运行所有检查
make check

# 单独的命令
make lint       # ruff 检查
make format     # ruff 格式化
make typecheck  # ty 类型检查
make test       # 带覆盖率的 pytest 测试

📚 详细文档

完整文档请访问 https://major.github.io/pcp-mcp

📄 许可证

本项目采用 MIT 许可证。