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

馃殌 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")

馃摎 Resources

Browse metrics via MCP resources:

• pcp://health - Quick system health summary
• pcp://metrics/common - Catalog of commonly used metrics
• pcp://namespaces - Live-discovered metric namespaces

馃挕 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