newrelic-mcp-nerdgraph
Connects AI agents to New Relic through the public NerdGraph GraphQL API, running locally with a User API key. Provides tools for running and validating NRQL queries across one or many accounts (including async long-running queries), searching and inspecting entities (tags, golden metrics, relationships), listing open alert issues, alert policies and NRQL conditions, searching and summarizing logs, retrieving distributed traces and transaction errors, listing recent deployments for change correlation, comparing metric windows, and optionally executing arbitrary NerdGraph GraphQL queries or mutations when explicitly enabled.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@newrelic-mcp-nerdgraph What is firing alerts for checkout service in the last hour?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
newrelic-mcp-nerdgraph
An open source MCP server that connects AI agents to New Relic through the public NerdGraph GraphQL API.
It runs locally over stdio with a standard User API key. There is no hosted bridge in the path, so every query is one you can read, reproduce in the NerdGraph GraphiQL explorer, and audit.
Why this exists
New Relic ships its own hosted MCP server. It is a good product, but it is a remote service gated behind account previews, and several of its tools require OAuth rather than an API key. This project targets a different set of constraints:
Local and self-hosted. Runs as a subprocess of your editor; telemetry never transits a third-party bridge.
Explicit NRQL instead of opaque translation. Tools either take NRQL you can read or generate NRQL that is returned alongside the results.
Read-only by default. Anything that changes New Relic configuration is behind an opt-in flag.
No extra cost. Only the New Relic account you already pay for.
See docs/comparison.md for a feature-by-feature comparison, and docs/architecture.md for the design.
Related MCP server: New Relic MCP Server
Install
uv tool install newrelic-mcp-nerdgraph
# or
pipx install newrelic-mcp-nerdgraphConfigure
You need a New Relic User API key
(NRAK-...) and your account id.
Variable | Required | Default | Purpose |
| yes | — | User API key |
| recommended | — | Comma-separated defaults, e.g. |
| no |
|
|
| no |
| Time window added to NRQL without one |
| no |
|
|
| no |
| Byte budget per tool response |
| no |
| Server-side NRQL timeout |
| no |
| Retries on 429/5xx |
| no |
| Mask credential-shaped strings in output |
| no |
| Expose the arbitrary-GraphQL tool |
| no |
| Allow write operations |
Cursor
~/.cursor/mcp.json:
{
"mcpServers": {
"newrelic": {
"command": "newrelic-mcp",
"env": {
"NEW_RELIC_API_KEY": "NRAK-your-key",
"NEW_RELIC_ACCOUNT_IDS": "1234567"
}
}
}
}Claude Desktop
claude_desktop_config.json uses the same shape. Run without installing:
{
"mcpServers": {
"newrelic": {
"command": "uvx",
"args": ["newrelic-mcp-nerdgraph"],
"env": { "NEW_RELIC_API_KEY": "NRAK-your-key", "NEW_RELIC_ACCOUNT_IDS": "1234567" }
}
}
}Tools
Tool | What it answers |
| Any NRQL query, one or many accounts |
| Long-running query, polled to completion |
| Check NRQL and see the clauses the server adds |
| Find services, hosts and lambdas by name, type or tag |
| Tags, golden metrics and relationships for one GUID |
| Currently firing alert issues |
| Alert policies in an account |
| Condition queries and thresholds |
| Logs by service, level, trace id or message |
| Error logs grouped by message pattern |
| Spans of one distributed trace |
| Transaction errors grouped by class |
| Recent deploys, for change correlation |
| An aggregate against the same window in the past |
| Arbitrary GraphQL (opt-in) |
Full input schemas: docs/tools.md.
Resources and prompts
newrelic://nrql/cheatsheet— event types, query patterns, common pitfalls.newrelic://playbook/investigation— the incident flow these tools are built for.newrelic://config— active configuration, API key excluded.Prompts:
investigate_incident,write_nrql.
Example session
"The checkout service is alerting. What happened in the last hour?"
The agent walks list_open_issues → get_entity → list_deployments →
get_recent_errors → get_trace → search_logs, each step narrowing the next.
docs/recipes.md has five worked examples.
Security
The API key lives in a
SecretStr, is attached per request, and never appears in logs,reproutput or the config resource.Every NRQL string is validated: no stacked statements, no comment markers, read-only verbs only. All interpolated values are escaped.
Credential-shaped strings in results (JWTs, bearer tokens, cloud keys) are masked before they reach the model.
Responses are size-capped so a wide query degrades into a truncated result rather than an unusable context.
Note that NRQL guardrails are a correctness and cost control, not an authorization boundary. The server can only read what the API key can read, so scope the key to the accounts the agent should see. Report vulnerabilities via SECURITY.md.
Development
uv sync --all-extras
uv run pytest
uv run ruff check . && uv run ruff format --check .
uv run mypyTests mock NerdGraph with respx; no account or network access is needed.
See CONTRIBUTING.md.
License
Apache-2.0. Not affiliated with or endorsed by New Relic, Inc.
Available Tools
14 toolscompare_metric_windowsBRead-onlyIdempotent
Compare an aggregate against the same window in the past.
The baseline makes a regression visible as a delta, which is usually more conclusive than an absolute value taken on its own.
Inputs: event_type (required), nrql_select (required), since, where, +2 more. Returns: result
get_entityARead-onlyIdempotent
Get one entity with its tags, golden metrics and relationships.
The golden metrics include the NRQL New Relic itself uses for that entity type, which you can run as-is through run_nrql.
Inputs: guid (required). Returns: result
get_recent_errorsCRead-onlyIdempotent
Show recent transaction errors grouped by error class.
Inputs: limit, since, account_ids, service_name. Returns: result
get_traceARead-onlyIdempotent
Get the spans of one distributed trace, in chronological order.
Pair this with search_logs on the same trace_id to see the request path and its log lines together.
Inputs: trace_id (required), limit, since, account_ids. Returns: result
list_alert_policiesCRead-onlyIdempotent
List alert policies for an account.
Inputs: cursor, account_id. Returns: result
list_deploymentsARead-onlyIdempotent
List recent deployments, newest first.
Use this to check whether an incident lines up with a release before digging into traces.
Inputs: limit, since, account_ids, entity_guid. Returns: result
list_nrql_conditionsBRead-onlyIdempotent
List NRQL alert conditions, including their queries and thresholds.
Reading the condition's own NRQL is the fastest way to reproduce what an alert saw at the time it fired.
Inputs: cursor, policy_id, account_id. Returns: result
list_open_issuesARead-onlyIdempotent
List alert issues, by default the ones currently active.
Each issue carries the entity GUIDs involved, which is the usual entry point for an on-call investigation.
Inputs: cursor, priority, only_open, account_id. Returns: result
run_nrqlARead-onlyIdempotent
Run a NRQL query against one or more New Relic accounts.
This is the general-purpose data tool: anything stored as events, metrics, logs or spans can be reached from here. Prefer the dedicated tools (search_logs, get_trace, get_recent_errors) when they fit, because they return a shape tuned for that use case.
Inputs: query (required), account_ids, timeout_seconds. Returns: result
run_nrql_asyncARead-onlyIdempotent
Run a NRQL query that exceeds the synchronous timeout, polling until it finishes.
Use this for wide time windows (days or weeks) or heavy aggregations. It is slower than run_nrql, so it is not the default choice.
Inputs: query (required), account_ids. Returns: result
search_entitiesARead-onlyIdempotent
Find entities (services, hosts, lambdas, browsers) by name, type or tag.
Start here when you only know a service name: the returned GUID is the key for get_entity, logs and alert lookups.
Inputs: name, tags, cursor, domain, +2 more. Returns: result
search_logsARead-onlyIdempotent
Search logs by service, level, trace id or message content.
Returns the newest matches first. Credential-shaped values in log messages are masked before the result leaves the server.
Inputs: level, limit, since, trace_id, +4 more. Returns: result
summarize_log_errorsARead-onlyIdempotent
Group error logs by message pattern to show what is failing most.
Prefer this over search_logs when the question is "what is broken" rather than "show me this specific request".
Inputs: limit, since, account_ids, service_name. Returns: result
validate_nrql_queryARead-onlyIdempotent
Check a NRQL query against the server guardrails without running it.
Returns the query as it would actually be sent, including the SINCE and LIMIT clauses that get appended automatically.
Inputs: query (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Most tools target clearly distinct resources or actions (entities, traces, logs, deployments, alerts). The main overlap is between general-purpose run_nrql/run_nrql_async/validate_nrql_query and specialized tools like search_logs, summarize_log_errors, and get_recent_errors, but the descriptions give useful selection guidance.
All tool names follow a predictable snake_case verb_noun pattern: get_entity, run_nrql, search_logs, list_open_issues, compare_metric_windows, etc. There are no mixed conventions or ambiguous abbreviations.
With 14 tools, the set is well-scoped for New Relic investigation workflows. Each tool appears to earn its place across entity lookup, NRQL execution, logs, traces, errors, alerts, deployments, and metric comparison.
The surface covers the core read-oriented investigation lifecycle: entities, NRQL, logs, traces, errors, alerts, deployments, and metric baselines. Some administrative or authoring operations (e.g. creating/updating alert policies or dashboards) are absent, but those may be outside this server's intended scope.
Maintenance
Related MCP Connectors
Access New Relic observability data through MCP - query metrics, logs, traces, entities, and more
Lets AI agents analyze API metrics, request logs, and traces, and manage apps and alerts.
Open-source agent that observes and fixes your application. Query logs, traces, metrics, incidents.
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to access New Relic logs and APM data through the NerdGraph API. It allows users to execute NRQL queries, retrieve application performance metrics, and analyze transaction traces using natural language.61MIT
- AlicenseBqualityCmaintenanceEnables natural language access to New Relic for monitoring, querying, and managing dashboards, entities, alerts, and deployments via the Model Context Protocol.529MIT
- FlicenseNot gradedqualityDmaintenanceEnables users to query and manage New Relic account data and features through natural language or specific commands, including NRQL queries, entity search, APM, Synthetics, and alerts management.3-
- FlicenseNot gradedqualityDmaintenanceProvides New Relic observability tools for AI assistants, enabling discovery, data access, alerting, incident response, and performance analytics via natural language queries.-