Skip to main content
Glama
newrelic-mcp-nerdgraph

newrelic-mcp-nerdgraph

newrelic-mcp-nerdgraph

CI PyPI Python License

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-nerdgraph

Configure

You need a New Relic User API key (NRAK-...) and your account id.

Variable

Required

Default

Purpose

NEW_RELIC_API_KEY

yes

—

User API key

NEW_RELIC_ACCOUNT_IDS

recommended

—

Comma-separated defaults, e.g. 123,456

NEW_RELIC_REGION

no

US

US or EU

NEW_RELIC_DEFAULT_SINCE

no

30 MINUTES AGO

Time window added to NRQL without one

NEW_RELIC_MAX_RESULT_ROWS

no

200

LIMIT added to NRQL without one

NEW_RELIC_MAX_RESPONSE_CHARS

no

100000

Byte budget per tool response

NEW_RELIC_QUERY_TIMEOUT_SECONDS

no

30

Server-side NRQL timeout

NEW_RELIC_MAX_RETRIES

no

3

Retries on 429/5xx

NEW_RELIC_REDACT_SENSITIVE_VALUES

no

true

Mask credential-shaped strings in output

NEW_RELIC_ENABLE_RAW_NERDGRAPH

no

false

Expose the arbitrary-GraphQL tool

NEW_RELIC_ENABLE_MUTATIONS

no

false

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

run_nrql

Any NRQL query, one or many accounts

run_nrql_async

Long-running query, polled to completion

validate_nrql_query

Check NRQL and see the clauses the server adds

search_entities

Find services, hosts and lambdas by name, type or tag

get_entity

Tags, golden metrics and relationships for one GUID

list_open_issues

Currently firing alert issues

list_alert_policies

Alert policies in an account

list_nrql_conditions

Condition queries and thresholds

search_logs

Logs by service, level, trace id or message

summarize_log_errors

Error logs grouped by message pattern

get_trace

Spans of one distributed trace

get_recent_errors

Transaction errors grouped by class

list_deployments

Recent deploys, for change correlation

compare_metric_windows

An aggregate against the same window in the past

nerdgraph_query

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, repr output 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 mypy

Tests 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 tools
compare_metric_windowsB
Read-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_entityA
Read-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_errorsC
Read-onlyIdempotent

Show recent transaction errors grouped by error class.

Inputs: limit, since, account_ids, service_name. Returns: result

get_traceA
Read-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_policiesC
Read-onlyIdempotent

List alert policies for an account.

Inputs: cursor, account_id. Returns: result

list_deploymentsA
Read-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_conditionsB
Read-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_issuesA
Read-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_nrqlA
Read-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_asyncA
Read-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_entitiesA
Read-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_logsA
Read-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_errorsA
Read-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_queryA
Read-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

    A3.6/5.0

    Scored across 14 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      6
      1
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables natural language access to New Relic for monitoring, querying, and managing dashboards, entities, alerts, and deployments via the Model Context Protocol.
      52
      9
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides New Relic observability tools for AI assistants, enabling discovery, data access, alerting, incident response, and performance analytics via natural language queries.
      -