Prometheus MCP Server

Instructions

Implementation Reference

• src/prometheus-client.ts:84-95 (handler)

  Core implementation of prom_range: sends HTTP GET to Prometheus /api/v1/query_range endpoint with parameters and filters results if includes specified.

  async range(query: string, start: string, end: string, step: string, includes?: string[]): Promise<PrometheusResponse<QueryResult>> {
    const response = await this.client.get<PrometheusResponse<QueryResult>>('/api/v1/query_range', {
      params: { query, start, end, step },
      timeout: 30000,
    });
    
    if (response.data.data && includes) {
      response.data.data = this.filterQueryResult(response.data.data, includes);
    }
    
    return response.data;
  }

• src/tools.ts:27-37 (schema)

  Input schema definition for the prom_range tool used in MCP tool registration.

  inputSchema: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'PromQL query expression' },
      start: { type: 'string', description: 'Start timestamp' },
      end: { type: 'string', description: 'End timestamp' },
      step: { type: 'string', description: 'Step interval (e.g., "15s", "1m")' },
      includes: { type: 'array', items: { type: 'string' }, description: 'Metric properties to include in response (optional)' },
    },
    required: ['query', 'start', 'end', 'step'],
  },

• src/tools.ts:24-38 (registration)

  Tool object registration for prom_range in the exported tools array.

  {
    name: 'prom_range',
    description: 'Execute a PromQL range query',
    inputSchema: {
      type: 'object',
      properties: {
        query: { type: 'string', description: 'PromQL query expression' },
        start: { type: 'string', description: 'Start timestamp' },
        end: { type: 'string', description: 'End timestamp' },
        step: { type: 'string', description: 'Step interval (e.g., "15s", "1m")' },
        includes: { type: 'array', items: { type: 'string' }, description: 'Metric properties to include in response (optional)' },
      },
      required: ['query', 'start', 'end', 'step'],
    },
  },

• src/tools.ts:101-107 (handler)

  Dispatch handler in handleToolCall function that validates args and invokes prometheusClient.range for prom_range tool.

  case 'prom_range': {
    if (!isPromRangeArgs(args)) {
      throw new Error('Invalid arguments for prom_range');
    }
    const { query, start, end, step, includes } = args;
    result = await prometheusClient.range(query, start, end, step, includes);
    break;

• src/tools.ts:70-73 (helper)

  Type guard helper to validate PromRangeArgs input for the prom_range tool.

  function isPromRangeArgs(args: unknown): args is PromRangeArgs {
    return typeof args === 'object' && args !== null && 
      'query' in args && 'start' in args && 'end' in args && 'step' in args;
  }