Performance Co-Pilot

pcp-mcp

MCP server for Performance Co-Pilot (PCP) metrics.

Query system performance metrics via the Model Context Protocol - CPU, memory, disk I/O, network, processes, and more.

📖 Full Documentation | 🚀 Getting Started

[CI] [codecov] [PyPI version] [Python 3.10+] [License: MIT]

🚀 Quick Start (No Install)

Run immediately with uvx — no installation required:

uvx pcp-mcp

Or install as a persistent global tool:

uvx tool install pcp-mcppcp-mcp

📦 Installation

pip install pcp-mcp

Or with uv:

uv add pcp-mcp

📋 Requirements

• Python: 3.10+
• PCP: Performance Co-Pilot with pmcd and pmproxy running
  bash

  # Fedora/RHEL/CentOSsudo dnf install pcpsudo systemctl enable --now pmcd pmproxy
  # Ubuntu/Debiansudo apt install pcpsudo systemctl enable --now pmcd pmproxy

⚙️ Configuration

Configure via environment variables:

🎯 Usage

Monitor localhost (default)

pcp-mcp

Monitor a remote host

PCP_TARGET_HOST=webserver1.example.com pcp-mcp

Or use the CLI flag:

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

Connect to remote pmproxy

PCP_HOST=metrics.example.com pcp-mcp

Use SSE transport

pcp-mcp --transport sse

🔌 MCP Client Configuration

Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json:

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

For remote monitoring:

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

💡 Using uvx means you don't need pcp-mcp installed — it runs directly from PyPI.

🛠️ Available Tools

System Monitoring

• get_system_snapshot - Point-in-time system overview (CPU, memory, disk, network, load)
• get_process_top - Top processes by CPU, memory, or I/O usage
• query_metrics - Fetch current values for specific PCP metrics
• search_metrics - Discover available metrics by name pattern
• describe_metric - Get detailed metadata about a metric

Example Queries

"What's the current CPU usage?"→ Uses get_system_snapshot
"Show me the top 10 processes by memory usage"→ Uses get_process_top(sort_by="memory", limit=10)
"What metrics are available for network traffic?"→ Uses search_metrics(pattern="network")
"Get detailed info about kernel.all.load"→ Uses describe_metric(name="kernel.all.load")

💡 Use Cases

Performance Troubleshooting

Ask Claude to:

• "Analyze current system performance and identify bottlenecks"
• "Why is my disk I/O so high?"
• "Which processes are consuming the most CPU?"

System Monitoring

• "Give me a health check of the production server"
• "Compare CPU usage over the last minute"
• "Monitor network traffic on eth0"

Capacity Planning

• "What's the memory utilization trend?"
• "Show me disk usage across all filesystems"
• "Analyze process resource consumption patterns"

🏗️ Architecture

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

• pcp-mcp: FastMCP server exposing PCP metrics via MCP tools
• pmproxy: PCP's REST API server (runs on port 44322 by default)
• pmcd: PCP metrics collector daemon
• Remote monitoring: Set PCP_TARGET_HOST to query a different pmcd instance via pmproxy

🔧 Development

# Install dependenciesuv sync --dev
# Run all checksmake check
# Individual commandsmake lint       # ruff checkmake format     # ruff formatmake typecheck  # ty checkmake test       # pytest with coverage

📖 Documentation

Full documentation at https://major.github.io/pcp-mcp

📄 License

MIT