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:

Variable	Description	Default
PCP_HOST	pmproxy host	localhost
PCP_PORT	pmproxy port	44322
PCP_TARGET_HOST	Target pmcd host to monitor	localhost
PCP_USE_TLS	Use HTTPS for pmproxy	false
PCP_TLS_VERIFY	Verify TLS certificates	true
PCP_TLS_CA_BUNDLE	Path to custom CA bundle	(optional)
PCP_TIMEOUT	Request timeout (seconds)	30
PCP_USERNAME	HTTP basic auth user	(optional)
PCP_PASSWORD	HTTP basic auth password	(optional)
PCP_ALLOWED_HOSTS	Hostspecs allowed via host param	(optional)

🎯 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