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