Prometheus MCP Server

# Usage Guide This guide explains how to use the Prometheus MCP Server with AI assistants like Claude. ## Available Tools The Prometheus MCP Server provides several tools that AI assistants can use to interact with your Prometheus data: ### Query Tools #### `execute_query` Executes an instant PromQL query and returns the current value(s). **Parameters:** - `query`: PromQL query string (required) - `time`: Optional RFC3339 or Unix timestamp (defaults to current time) **Example Claude prompt:** ``` Use the execute_query tool to check the current value of the 'up' metric. ``` #### `execute_range_query` Executes a PromQL range query to return values over a time period. **Parameters:** - `query`: PromQL query string (required) - `start`: Start time as RFC3339 or Unix timestamp (required) - `end`: End time as RFC3339 or Unix timestamp (required) - `step`: Query resolution step width (e.g., '15s', '1m', '1h') (required) **Example Claude prompt:** ``` Use the execute_range_query tool to show me the CPU usage over the last hour with 5-minute intervals. Use the query 'rate(node_cpu_seconds_total{mode="user"}[5m])'. ``` ### Discovery Tools #### `list_metrics` Retrieves a list of all available metric names. **Example Claude prompt:** ``` Use the list_metrics tool to show me all available metrics in my Prometheus server. ``` #### `get_metric_metadata` Retrieves metadata about a specific metric. **Parameters:** - `metric`: The name of the metric (required) **Example Claude prompt:** ``` Use the get_metric_metadata tool to get information about the 'http_requests_total' metric. ``` #### `get_targets` Retrieves information about all Prometheus scrape targets. **Example Claude prompt:** ``` Use the get_targets tool to check the health of all monitoring targets. ``` ## Example Workflows ### Basic Monitoring Check ``` Can you check if all my monitored services are up? Also, show me the top 5 CPU-consuming pods if we're monitoring Kubernetes. ``` Claude might use: 1. `execute_query` with `up` to check service health 2. `execute_query` with a more complex PromQL query to find CPU usage ### Performance Analysis ``` Analyze the memory usage pattern of my application over the last 24 hours. Are there any concerning spikes? ``` Claude might use: 1. `execute_range_query` with appropriate time parameters 2. Analyze the data for patterns and anomalies ### Metric Exploration ``` I'm not sure what metrics are available. Can you help me discover metrics related to HTTP requests and then show me their current values? ``` Claude might use: 1. `list_metrics` to get all metrics 2. Filter for HTTP-related metrics 3. `get_metric_metadata` to understand what each metric represents 4. `execute_query` to fetch current values ## Tips for Effective Use 1. **Be specific about time ranges** when asking for historical data 2. **Specify step intervals** appropriate to your time range (e.g., use smaller steps for shorter periods) 3. **Use metric discovery tools** if you're unsure what metrics are available 4. **Start with simple queries** and gradually build more complex ones 5. **Ask for explanations** if you don't understand the returned data ## PromQL Query Examples Here are some useful PromQL queries you can use with the tools: ### Basic Queries - Check if targets are up: `up` - HTTP request rate: `rate(http_requests_total[5m])` - CPU usage: `sum(rate(node_cpu_seconds_total{mode!="idle"}[5m])) by (instance)` - Memory usage: `node_memory_MemTotal_bytes - node_memory_MemFree_bytes - node_memory_Buffers_bytes - node_memory_Cached_bytes` ### Kubernetes-specific Queries - Pod CPU usage: `sum(rate(container_cpu_usage_seconds_total{container!="POD",container!=""}[5m])) by (pod)` - Pod memory usage: `sum(container_memory_working_set_bytes{container!="POD",container!=""}) by (pod)` - Pod restart count: `kube_pod_container_status_restarts_total` ## Limitations - The MCP server queries your live Prometheus instance, so it only has access to metrics retained in your Prometheus server's storage - Complex PromQL queries might take longer to execute, especially over large time ranges - Authentication is passed through from your environment variables, so ensure you're using credentials with appropriate access rights