newrelic-mcp-server

A comprehensive MCP server for NewRelic with 25 tools for querying, monitoring, and analyzing your observability data — NRQL, entities, alerts, dashboards, logs, and more.

Quick Start

Using npx

Add to your .mcp.json:

{
  "mcpServers": {
    "newrelic": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ruminaider/newrelic-mcp-server"],
      "env": {
        "NEW_RELIC_API_KEY": "NRAK-XXXXXXXXXXXX",
        "NEW_RELIC_ACCOUNT_ID": "1234567"
      }
    }
  }
}

Using Docker

docker build -t newrelic-mcp-server .

{
  "mcpServers": {
    "newrelic": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "NEW_RELIC_API_KEY", "-e", "NEW_RELIC_ACCOUNT_ID", "-e", "NEW_RELIC_REGION", "newrelic-mcp-server"],
      "env": {
        "NEW_RELIC_API_KEY": "NRAK-XXXXXXXXXXXX",
        "NEW_RELIC_ACCOUNT_ID": "1234567",
        "NEW_RELIC_REGION": "US"
      }
    }
  }
}

Authentication

The server authenticates via a NewRelic User API key (recommended over license keys):

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | NEW_RELIC_API_KEY | Yes | - | User API key (format: NRAK-XXXXXXXXXXXX) | | NEW_RELIC_ACCOUNT_ID | Yes | - | NewRelic Account ID | | NEW_RELIC_REGION | No | US | API region (US or EU) | | LOG_LEVEL | No | info | Log level (debug / info / warn / error) |

API keys are automatically redacted in log output.

Performance

Response Optimization

All tool responses use compact JSON (no whitespace) to reduce token usage. Tools that build structured response objects include only essential fields — verbose NerdGraph metadata like __typename, permalink, and rawConfiguration is stripped when raw API data is returned.

Rate Limiting

The server enforces NewRelic's API limits:

• 25 concurrent requests with semaphore-based backpressure
• Exponential backoff on 429 responses (base 1s, max 30s, with jitter)
• Automatic retry for rate limit and network errors (3 attempts)

Tools

Data Access — 5 tools

| Tool | Description | |------|-------------| | execute_nrql_query | Execute arbitrary NRQL queries with full result parsing | | list_recent_logs | List recent logs with filtering by time range and entity | | analyze_entity_logs | Analyze logs for a specific entity with pattern detection | | query_logs | Search logs by field/value with configurable limits | | natural_language_to_nrql_query | Get NRQL query suggestions from natural language descriptions |

Entity Management — 5 tools

| Tool | Description | |------|-------------| | get_entity | Get entity details by GUID including summary metrics | | list_related_entities | Find entities related to a given entity | | search_entity_with_tag | Search entities by tag key/value pairs | | list_entity_types | List all available entity types and domains | | list_available_new_relic_accounts | List accessible NewRelic accounts |

Alerts & Incidents — 8 tools

| Tool | Description | |------|-------------| | list_alert_policies | List alert policies with condition counts | | list_alert_conditions | List NRQL alert conditions for a policy | | list_recent_issues | List recent AI-detected issues (experimental) | | search_incident | Search incidents by time range and entity | | analyze_deployment_impact | Analyze deployment effects on error rates and throughput | | generate_alert_insights_report | Generate comprehensive alert analysis reports | | get_entity_error_groups | Get error groups for an entity with occurrence counts | | list_change_events | List deployment and change tracking events |

Dashboards & Synthetics — 3 tools

| Tool | Description | |------|-------------| | get_dashboard | Get dashboard details including widgets and NRQL queries | | list_dashboards | List all dashboards with pagination | | list_synthetic_monitors | List synthetic monitors with status and locations |

Performance Analysis — 3 tools

| Tool | Description | |------|-------------| | analyze_golden_metrics | Analyze entity golden metrics (throughput, errors, latency) | | analyze_transactions | Analyze transaction performance with slowest breakdown | | convert_time_period_to_epoch_ms | Convert human-readable time periods to epoch milliseconds |

Utility — 1 tool

| Tool | Description | |------|-------------| | convert_time_period_to_epoch_ms | Convert time descriptions like "last 6 hours" to epoch timestamps |

Example Usage

Query Error Rates

execute_nrql_query with:
  query: "SELECT percentage(count(*), WHERE error IS true) FROM Transaction SINCE 1 hour ago"

Find Slow Transactions

analyze_transactions with:
  entityGuid: "YOUR_APM_ENTITY_GUID"
  sinceMinutesAgo: 60

Search Logs for Errors

query_logs with:
  field: "level"
  value: "ERROR"
  limit: 100

Get Help Writing NRQL

natural_language_to_nrql_query with:
  description: "Show me error rates by service over the last 6 hours"

Development

pnpm install       # install dependencies
pnpm build         # compile TypeScript
pnpm test          # run tests
pnpm dev           # run with tsx (no build needed)
pnpm watch         # recompile on change
pnpm lint          # lint with Biome
pnpm format        # format with Biome

Project Structure

src/
  index.ts                    # Entry point (stdio transport)
  server.ts                   # MCP server creation and tool registration
  config.ts                   # Environment variable parsing and validation
  services/
    nerdgraph-client.ts       # Core GraphQL client with rate limiting and retry
    nrql-service.ts           # NRQL query execution
    log-service.ts            # Log querying and analysis
    entity-service.ts         # Entity retrieval and relationships
    alert-service.ts          # Alert policies, conditions, and incidents
    dashboard-service.ts      # Dashboard retrieval and listing
    synthetic-service.ts      # Synthetic monitor management
    performance-service.ts    # Transaction and golden metrics analysis
  tools/
    nrql-tools.ts             # NRQL query tools
    entity-tools.ts           # Entity management tools
    alert-tools.ts            # Alert and incident tools
    incident-tools.ts         # Incident search and analysis tools
    dashboard-tools.ts        # Dashboard tools
    log-tools.ts              # Log query tools
    performance-tools.ts      # Performance analysis tools
    synthetic-tools.ts        # Synthetic monitor tools
    account-tools.ts          # Account listing tools
    utility-tools.ts          # Time conversion utilities
  types/
    newrelic.ts               # NewRelic API type definitions
  utils/
    errors.ts                 # Custom error types (AuthenticationError, RateLimitError, etc.)
    logger.ts                 # Structured stderr logging with API key redaction
    response.ts               # Response optimization (field stripping, compact JSON)
    retry.ts                  # Exponential backoff retry with jitter

Docker Development

docker compose build                              # build image
docker compose run --rm newrelic-mcp               # run server
docker compose --profile dev up newrelic-mcp-dev   # dev mode with hot reload

Troubleshooting

"Missing required environment variables"

Ensure NEW_RELIC_API_KEY and NEW_RELIC_ACCOUNT_ID are set and passed to Docker.

"Authentication failed"

Verify your API key has appropriate permissions. User API keys (NRAK-...) are recommended.

"Rate limit exceeded"

The server automatically retries with backoff. If persistent, reduce query frequency.

aiIssues endpoints failing

These use experimental NerdGraph headers. The server handles this automatically for list_recent_issues and search_incident.

License

MIT