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](https://major.github.io/pcp-mcp) | 🚀 [Getting Started](https://major.github.io/pcp-mcp/getting-started/)

🚀 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-mcp

pcp-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

  # 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

⚙️ 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 dependencies

uv sync --dev

Run all checks

make check

Individual commands

make lint # ruff check make format # ruff format make typecheck # ty check make test # pytest with coverage

📖 Documentation

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

📄 License

MIT