Grafana MCP Server

Instructions

Implementation Reference

• src/tools/pyroscope.ts:66-96 (handler)

  The ToolDefinition export for 'list_pyroscope_label_names' including the core handler function that executes the tool logic: creates an axios client for the Pyroscope datasource, handles time ranges and matchers, queries the /pyroscope/api/v1/label-names endpoint, filters out internal labels (starting with '__'), and returns the list of label names.

  export const listPyroscopeLabelNames: ToolDefinition = {
    name: 'list_pyroscope_label_names',
    description: 'Lists all available label names found in profiles within a Pyroscope datasource',
    inputSchema: ListPyroscopeLabelNamesSchema,
    handler: async (params, context: ToolContext) => {
      try {
        const client = createPyroscopeClient(context.config.grafanaConfig, params.data_source_uid);
        const timeRange = params.start_rfc_3339 || params.end_rfc_3339 
          ? { start: '', end: '' } 
          : getDefaultTimeRange();
        
        const queryParams: any = {
          start: params.start_rfc_3339 || timeRange.start,
          end: params.end_rfc_3339 || timeRange.end,
        };
        
        if (params.matchers) {
          queryParams.matchers = params.matchers;
        }
        
        const response = await client.get('/pyroscope/api/v1/label-names', { params: queryParams });
        
        // Filter out internal labels (those starting with __)
        const labels = (response.data.data || []).filter((label: string) => !label.startsWith('__'));
        
        return createToolResult(labels);
      } catch (error: any) {
        return createErrorResult(error.response?.data?.message || error.message);
      }
    },
  };

• src/tools/pyroscope.ts:6-11 (schema)

  Zod schema defining the input parameters for the list_pyroscope_label_names tool: data_source_uid (required), optional start/end times in RFC3339, and optional Prometheus-style matchers.

  const ListPyroscopeLabelNamesSchema = z.object({
    data_source_uid: z.string().describe('The UID of the datasource to query'),
    start_rfc_3339: z.string().optional().describe('Start time in RFC3339 format'),
    end_rfc_3339: z.string().optional().describe('End time in RFC3339 format'),
    matchers: z.string().optional().describe('Prometheus-style matchers'),
  });

• src/tools/pyroscope.ts:199-199 (registration)

  The server.registerTool call that registers the list_pyroscope_label_names tool within the registerPyroscopeTools function.

  server.registerTool(listPyroscopeLabelNames);

• src/tools/pyroscope.ts:37-53 (helper)

  Helper function createPyroscopeClient used by the handler to create an axios instance configured for the specific Pyroscope datasource with authentication.

  function createPyroscopeClient(config: any, datasourceUid: string) {
    const headers: any = {
      'User-Agent': 'mcp-grafana/1.0.0',
    };
    
    if (config.serviceAccountToken) {
      headers['Authorization'] = `Bearer ${config.serviceAccountToken}`;
    } else if (config.apiKey) {
      headers['Authorization'] = `Bearer ${config.apiKey}`;
    }
    
    return axios.create({
      baseURL: `${config.url}/api/datasources/proxy/uid/${datasourceUid}`,
      headers,
      timeout: 30000,
    });
  }

• src/tools/pyroscope.ts:56-63 (helper)

  Helper function getDefaultTimeRange used by the handler to provide default start/end times (last hour) if not specified in parameters.

  function getDefaultTimeRange(): { start: string; end: string } {
    const now = new Date();
    const oneHourAgo = new Date(now.getTime() - 60 * 60 * 1000);
    return {
      start: oneHourAgo.toISOString(),
      end: now.toISOString(),
    };
  }