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.

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.

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

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.