run_nrql_query
Execute NRQL queries to analyze New Relic metrics and events directly from the MCP Server, enabling targeted data insights with optional account-specific filtering.
Instructions
Execute NRQL queries against New Relic data to analyze metrics and events
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| nrql | Yes | The NRQL query to execute | |
| target_account_id | No | Optional New Relic account ID to query |
Implementation Reference
- src/tools/nrql.ts:44-64 (handler)The execute method in NrqlTool class that implements the core logic for the 'run_nrql_query' tool: validates inputs and delegates to NewRelicClient.runNrqlQuery.async execute(input: { nrql?: string; target_account_id?: string }): Promise<NrqlQueryResult> { // Validate input if (!input.nrql || typeof input.nrql !== 'string' || input.nrql.trim() === '') { throw new Error('Invalid or empty NRQL query provided'); } if (!input.target_account_id) { throw new Error('Account ID must be provided'); } if (input.target_account_id && !/^\d+$/.test(input.target_account_id)) { throw new Error('Invalid account ID format'); } const result = await this.client.runNrqlQuery({ nrql: input.nrql, accountId: input.target_account_id, }); return result; }
- src/tools/nrql.ts:27-42 (schema)Input schema definition for the 'run_nrql_query' tool, defining properties for nrql (required) and target_account_id (optional).getInputSchema() { return { type: 'object' as const, properties: { nrql: { type: 'string', description: 'The NRQL query to execute', }, target_account_id: { type: 'string', description: 'Optional New Relic account ID to query', }, }, required: ['nrql'], }; }
- src/server.ts:165-169 (registration)Registration and dispatch handler in NewRelicMCPServer.executeTool switch statement that specifically handles 'run_nrql_query' by instantiating NrqlTool and calling its execute method.case 'run_nrql_query': return await new NrqlTool(this.client).execute({ ...args, target_account_id: accountId, });
- src/client/newrelic-client.ts:94-167 (helper)Supporting helper method in NewRelicClient that executes the NRQL query via NerdGraph GraphQL API, handles errors, and formats the result.async runNrqlQuery(params: { nrql: string; accountId: string }): Promise<NrqlQueryResult> { if (!params.nrql || typeof params.nrql !== 'string') { throw new Error('Invalid or empty NRQL query provided'); } if (!params.accountId || !/^\d+$/.test(params.accountId)) { throw new Error('Invalid account ID format'); } const query = `{ actor { account(id: ${params.accountId}) { nrql(query: "${params.nrql.replace(/"/g, '\\"')}") { results metadata { eventTypes timeWindow { begin end } facets } } } } }`; try { type NrqlResponse = { actor?: { account?: { nrql?: { results?: Array<Record<string, unknown>>; metadata?: { eventTypes?: string[]; timeWindow?: { begin: number; end: number }; facets?: string[]; }; }; }; }; }; const response = (await this.executeNerdGraphQuery<NrqlResponse>( query )) as GraphQLResponse<NrqlResponse>; if (response.errors) { const errorMessage = response.errors[0]?.message || 'NRQL query failed'; throw new Error(errorMessage); } const nrqlResult = response.data?.actor?.account?.nrql; if (!nrqlResult) { throw new Error('No results returned from NRQL query'); } // Detect if it's a time series query const isTimeSeries = params.nrql.toLowerCase().includes('timeseries'); return { results: nrqlResult.results || [], metadata: { ...nrqlResult.metadata, timeSeries: isTimeSeries, }, }; } catch (error: unknown) { if (error instanceof Error && error.message.includes('Syntax error')) { throw new Error(`NRQL Syntax error: ${error.message}`); } throw error instanceof Error ? error : new Error(String(error)); } }
- src/server.ts:69-105 (registration)Tool registration block in NewRelicMCPServer.registerTools() where NrqlTool definition is added to the tools array and registered in the server's tools Map for discovery.const tools = [ nrqlTool.getToolDefinition(), apmTool.getListApplicationsTool(), entityTool.getSearchTool(), entityTool.getDetailsTool(), alertTool.getPoliciesTool(), alertTool.getIncidentsTool(), alertTool.getAcknowledgeTool(), syntheticsTool.getListMonitorsTool(), syntheticsTool.getCreateMonitorTool(), nerdGraphTool.getQueryTool(), // REST v2 tools restDeployments.getCreateTool(), restDeployments.getListTool(), restDeployments.getDeleteTool(), restApm.getListApplicationsTool(), restMetrics.getListMetricNamesTool(), restMetrics.getMetricDataTool(), restMetrics.getListApplicationHostsTool(), { name: 'get_account_details', description: 'Get New Relic account details', inputSchema: { type: 'object' as const, properties: { target_account_id: { type: 'string' as const, description: 'Optional account ID to get details for', }, }, }, }, ]; tools.forEach((tool) => { this.tools.set(tool.name, tool); });