query_prometheus
Execute PromQL queries against Prometheus data sources to retrieve instant metrics or time series data for monitoring and analysis.
Instructions
Query Prometheus using a PromQL expression. Supports both instant and range queries.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| datasourceUid | Yes | The UID of the datasource to query | |
| endTime | No | The end time for range queries | |
| expr | Yes | The PromQL expression to query | |
| queryType | Yes | The type of query to use | |
| startTime | Yes | The start time (RFC3339 or relative like "now-1h") | |
| stepSeconds | No | The time series step size in seconds for range queries |
Implementation Reference
- src/tools/prometheus.ts:100-123 (handler)Full ToolDefinition object for 'query_prometheus' tool, including the async handler function that executes PromQL queries (instant or range) via PrometheusClient.
export const queryPrometheus: ToolDefinition = { name: 'query_prometheus', description: 'Query Prometheus using a PromQL expression. Supports both instant and range queries.', inputSchema: QueryPrometheusSchema, handler: async (params, context: ToolContext) => { try { const client = new PrometheusClient(context.config.grafanaConfig, params.datasourceUid); let result; if (params.queryType === 'instant') { result = await client.query(params.expr, parseTime(params.startTime)); } else { const start = parseTime(params.startTime); const end = params.endTime ? parseTime(params.endTime) : 'now'; const step = params.stepSeconds ? `${params.stepSeconds}s` : '60s'; result = await client.queryRange(params.expr, start, end, step); } return createToolResult(result); } catch (error: any) { return createErrorResult(error.message); } }, }; - src/tools/prometheus.ts:5-12 (schema)Zod schema defining the input parameters for the query_prometheus tool.
const QueryPrometheusSchema = z.object({ datasourceUid: z.string().describe('The UID of the datasource to query'), expr: z.string().describe('The PromQL expression to query'), queryType: z.enum(['range', 'instant']).describe('The type of query to use'), startTime: z.string().describe('The start time (RFC3339 or relative like "now-1h")'), endTime: z.string().optional().describe('The end time for range queries'), stepSeconds: z.number().optional().describe('The time series step size in seconds for range queries'), }); - src/tools/prometheus.ts:232-238 (registration)Registration function that registers the query_prometheus tool (and other Prometheus tools) with the MCP server.
export function registerPrometheusTools(server: any) { server.registerTool(queryPrometheus); server.registerTool(listPrometheusMetricNames); server.registerTool(listPrometheusLabelNames); server.registerTool(listPrometheusLabelValues); server.registerTool(listPrometheusMetricMetadata); } - src/tools/prometheus.ts:58-81 (helper)Helper function parseTime used by the query_prometheus handler to convert relative times (e.g., 'now-1h') to Unix timestamps.
function parseTime(time: string): string { if (time === 'now') { return Math.floor(Date.now() / 1000).toString(); } const relativeMatch = time.match(/^now-(\d+)([smhd])$/); if (relativeMatch) { const value = parseInt(relativeMatch[1]); const unit = relativeMatch[2]; let seconds = 0; switch (unit) { case 's': seconds = value; break; case 'm': seconds = value * 60; break; case 'h': seconds = value * 3600; break; case 'd': seconds = value * 86400; break; } return Math.floor((Date.now() / 1000) - seconds).toString(); } // Assume it's already a Unix timestamp or RFC3339 return time; }