Prometheus Monitoring

Prometheus Monitoring

MCP Server

How to Run

# stdio mode (default — used by NetClaw)
PROMETHEUS_URL=http://prometheus:9090 prometheus-mcp-server

# HTTP transport mode
PROMETHEUS_MCP_SERVER_TRANSPORT=http PROMETHEUS_URL=http://prometheus:9090 prometheus-mcp-server

# With basic auth
PROMETHEUS_URL=http://prometheus:9090 PROMETHEUS_USERNAME=admin PROMETHEUS_PASSWORD=secret prometheus-mcp-server

# With bearer token (Grafana Cloud, Thanos, etc.)
PROMETHEUS_URL=https://prom.example.com PROMETHEUS_TOKEN=your_bearer_token prometheus-mcp-server

Environment Variables

Tools

Workflow: Network Device Metric Monitoring

When checking Prometheus for network device metrics:

1. Health check: health_check — verify Prometheus is reachable
2. Discover metrics: list_metrics — find available SNMP/device metrics
3. Metric metadata: get_metric_metadata(metric="ifHCInOctets") — check type and description
4. Instant query: execute_query(query="up{job='snmp'}") — check which targets are up
5. Range query: execute_range_query — trend analysis over time:
   • Interface traffic: rate(ifHCInOctets{instance="router1"}[5m]) * 8
   • CPU utilization: device_cpu_utilization{device="core-rtr-01"}
   • Interface errors: increase(ifInErrors{device=~".*"}[1h])
   • BGP peer state: bgp_peer_state{peer="10.1.1.2"}
6. Scrape targets: get_targets — verify SNMP exporters and device scrape health
7. GAIT: Record all queries in audit trail

Example: Interface Utilization Check

health_check()
list_metrics(page=1, page_size=50)
execute_query(query="rate(ifHCInOctets{device='core-rtr-01'}[5m]) * 8")
execute_range_query(query="rate(ifHCOutOctets{device='core-rtr-01'}[5m]) * 8", start="2024-01-01T00:00:00Z", end="2024-01-01T01:00:00Z", step="60s")
get_targets()

Workflow: Alert Threshold Investigation

When investigating whether metrics are crossing alert thresholds:

1. Discover metrics: list_metrics — find the metric name
2. Check metadata: get_metric_metadata — understand metric type (counter, gauge, histogram)
3. Current value: execute_query — get current metric value
4. Historical trend: execute_range_query — check trend over past 1h/6h/24h
5. Compare targets: get_targets — check if specific exporters are down
6. Report: Metric analysis with current value, trend direction, and recommendation

Workflow: Capacity Planning

When analyzing capacity trends for network infrastructure:

1. Discover metrics: list_metrics — find bandwidth/utilization metrics
2. Peak analysis: execute_range_query with max_over_time():
   • max_over_time(rate(ifHCInOctets{device="core-rtr-01",ifName="Gi0/0"}[5m])[7d:1h]) * 8
3. 95th percentile: execute_range_query with quantile_over_time():
   • quantile_over_time(0.95, rate(ifHCInOctets{device="core-rtr-01"}[5m])[30d:1h]) * 8
4. Growth rate: Compare weekly/monthly averages
5. Report: Utilization summary with capacity headroom and growth projection

Integration with Other Skills

Important Rules

• Prefer read-only operations — all 6 tools are read-only; no Prometheus configuration changes
• Use pagination for metric lists — list_metrics supports page and page_size to avoid large responses
• Specify time ranges carefully — overly broad execute_range_query time ranges return large result sets
• Disable links for context efficiency — set PROMETHEUS_DISABLE_LINKS=true to reduce response size
• GAIT audit mandatory — record all Prometheus queries and metric analysis in audit trail
• No secrets in queries — never embed credentials or sensitive data in PromQL expressions
• Verify connectivity first — use health_check before running queries to confirm Prometheus is reachable

Error Handling

• Auth fails (401/403): Check PROMETHEUS_URL, PROMETHEUS_USERNAME/PROMETHEUS_PASSWORD, or PROMETHEUS_TOKEN in ~/.openclaw/.env. Verify Prometheus allows the configured auth method.
• Connection refused: Verify PROMETHEUS_URL is reachable. Use health_check to diagnose connectivity.
• PromQL syntax errors: Use list_metrics and get_metric_metadata to discover valid metric names before querying.
• Empty results: Check get_targets to verify scrape targets are up and the expected labels exist.
• Timeout errors: Increase PROMETHEUS_REQUEST_TIMEOUT for slow queries or large result sets.
• SSL errors: Set PROMETHEUS_URL_SSL_VERIFY=false for self-signed certificates (development only).