Grafana MCP Server

Instructions

Implementation Reference

• src/tools/alerting.ts:32-60 (handler)

  The main handler function for the 'list_alert_rules' tool. It constructs filters from input params, calls GrafanaClient.listAlertRules, formats the rules into a summary (uid, title, state, labels, folder), and returns the result or error.

  handler: async (params, context: ToolContext) => {
    try {
      const client = new GrafanaClient(context.config.grafanaConfig);
      
      // Build filters object for API
      const filters: any = {};
      if (params.label_selectors) {
        // Convert label selectors to query params
        // Note: Real implementation would need proper label selector formatting
        filters.labels = params.label_selectors;
      }
      if (params.limit) filters.limit = params.limit;
      if (params.page) filters.page = params.page;
      
      const rules = await client.listAlertRules(filters);
      
      // Format the response
      const formatted = rules.map((rule: any) => ({
        uid: rule.uid,
        title: rule.title,
        state: rule.state || 'inactive',
        labels: rule.labels || {},
        folder: rule.folderUID,
      }));
      
      return createToolResult(formatted);
    } catch (error: any) {
      return createErrorResult(error.message);
    }

• src/tools/alerting.ts:6-16 (schema)

  Zod schema defining the input parameters for the list_alert_rules tool: optional label_selectors, limit, and page.

  const ListAlertRulesSchema = z.object({
    label_selectors: z.array(z.object({
      filters: z.array(z.object({
        name: z.string().describe('The name of the label to match against'),
        value: z.string().describe('The value to match against'),
        type: z.enum(['=', '!=', '=~', '!~']).describe('The match operator'),
      })),
    })).optional().describe('Label matchers to filter alert rules'),
    limit: z.number().optional().describe('Maximum number of results to return'),
    page: z.number().optional().describe('Page number to return'),
  });

• src/tools/alerting.ts:113-117 (registration)

  Registration function that registers the list_alert_rules tool (along with related tools) to the MCP server.

  export function registerAlertingTools(server: any) {
    server.registerTool(listAlertRules);
    server.registerTool(getAlertRuleByUid);
    server.registerTool(listContactPoints);
  }

• src/clients/grafana-client.ts:122-131 (helper)

  Helper method in GrafanaClient that performs the actual API call to list alert rules from Grafana's provisioning endpoint, used by the tool handler.

  async listAlertRules(filters?: any): Promise<AlertRule[]> {
    try {
      const response = await this.client.get('/api/v1/provisioning/alert-rules', {
        params: filters,
      });
      return response.data;
    } catch (error) {
      this.handleError(error);
    }
  }