New Relic MCP Server

A comprehensive Model Context Protocol (MCP) server for New Relic monitoring, observability, and management operations.

Features

Core Monitoring & Observability

• NRQL Query Execution: Run custom New Relic Query Language queries
• Application Performance: Real-time performance metrics (response time, throughput)
• Error Monitoring: Error rates, counts, and detailed error analysis
• Infrastructure Monitoring: Host metrics, CPU, memory, disk usage
• Incident Management: Recent incidents, violations, and alert status

Dashboard Management

• Dashboard Operations: Create, read, update, and delete dashboards
• Widget Management: Add, update, and remove dashboard widgets with rawConfiguration support for dual y-axis, fixed y-axis ranges, legend control, and chart styles
• Search & Discovery: Find dashboards by name or GUID
• Visualization Support: Line charts, bar charts, pie charts, tables, billboards

Entity Management

• Entity Search: Find any New Relic entity (APM apps, hosts, synthetic monitors, browsers) by name, type, domain, or tags
• Entity Tagging: Add, update, and delete tags on any entity
• Service Levels: List all SLIs/SLOs with compliance data and objectives
• Synthetic Monitors: List monitors with status, success rate, and location health; query recent check results

Alert & Notification System

• Alert Policies: Create and manage alert policies with configurable incident preferences
• NRQL Conditions: Set up custom alert conditions with thresholds and triggers
• Notification Destinations: Configure email, Slack, webhook, PagerDuty integrations
• Notification Channels: Link destinations to specific notification preferences
• Workflows: Connect alert policies to notification channels with filtering

Deployment Tracking

• Deployment Markers: Track deployment events and their impact
• Release Correlation: Correlate performance changes with deployments

Installation

Prerequisites

• Python 3.11+ (recommended: use uv for fast dependency management)
• New Relic User API Key (not Ingest key)
• New Relic Account ID

Quick Start

# Clone the repository
git clone <repository-url>
cd mcp-newrelic

# Install dependencies (using uv - recommended)
uv sync

# Or using pip
pip install -e .

# Configure your credentials (see Configuration section below)

Setup

Getting Your Credentials

1. API Key: Go to New Relic API Keys → Create User API Key
2. Account ID: Found in your New Relic URL: https://one.newrelic.com/accounts/{ACCOUNT_ID}/...
3. Region: Use "EU" if your account is on one.eu.newrelic.com, otherwise "US"

MCP Client Integration

Add the server to your MCP client config. You do not need to start the server manually — your MCP client launches it automatically.

{
  "mcpServers": {
    "newrelic": {
      "command": "uv",
      "args": ["run", "python", "/path/to/mcp-newrelic/server.py"],
      "env": {
        "NEW_RELIC_API_KEY": "your-api-key",
        "NEW_RELIC_ACCOUNT_ID": "your-account-id"
      }
    }
  }
}

Where this config lives depends on your client (e.g., ~/.claude.json for Claude Code, claude_desktop_config.json for Claude Desktop, .cursor/mcp.json for Cursor, etc.). Replace /path/to/mcp-newrelic/server.py with the actual path to your clone.

Alternatively, use the newrelic-mcp console script instead of pointing at server.py:

{
  "mcpServers": {
    "newrelic": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-newrelic", "newrelic-mcp"],
      "env": {
        "NEW_RELIC_API_KEY": "your-api-key",
        "NEW_RELIC_ACCOUNT_ID": "your-account-id"
      }
    }
  }
}

Advanced Configuration

If you need to run the server manually (e.g., for development or debugging), it supports flexible configuration with clear precedence (highest to lowest):

1. Command Line Arguments (Highest Priority)

uv run python server.py \
  --api-key "NRAK-your-api-key" \
  --account-id "your-account-id" \
  --region "US"

2. JSON Configuration File

# Copy and edit the example config
cp newrelic-config.json.example config/newrelic-config.json

# Run with config file
uv run python server.py --config config/newrelic-config.json

Example newrelic-config.json:

{
  "api_key": "NRAK-your-api-key",
  "account_id": "your-account-id",
  "region": "US",
  "timeout": 30
}

3. Environment Variables (Lowest Priority)

export NEW_RELIC_API_KEY="NRAK-your-api-key"
export NEW_RELIC_ACCOUNT_ID="your-account-id"
export NEW_RELIC_REGION="US"  # US or EU
export NEW_RELIC_TIMEOUT="30"

Available Tools

NRQL & Monitoring

• query_nrql: Execute custom NRQL queries with full flexibility
• get_app_performance: Application performance metrics (avg/p95 response time, throughput)
• get_app_errors: Error metrics, counts, and error analysis
• get_incidents: Recent incidents with time filtering
• get_infrastructure_hosts: Infrastructure host metrics (CPU, memory, disk)
• get_alert_violations: Recent alert violations and status
• get_deployments: Deployment markers and impact analysis

Dashboard Management

• get_dashboards: List and search dashboards with filtering
• get_dashboard_widgets: Retrieve all widgets from a dashboard
• create_dashboard: Create new dashboards for monitoring
• update_dashboard: Rename a dashboard and/or update its description (pages and widgets preserved)
• delete_dashboard: Delete a dashboard by GUID
• add_widget_to_dashboard: Add custom NRQL-based widgets
• update_widget: Update existing dashboard widgets
• delete_widget: Remove widgets from dashboards

Entity Management

• entity_search: Search for any entity by name, type (APPLICATION, HOST, MONITOR, KEY_TRANSACTION), or domain (APM, INFRA, SYNTH, BROWSER, EXT). Supports limit (default 25, max 200) and minimal_output to reduce response size.
• get_entity: Look up a single entity by GUID with full details (name, type, account, tags, permalink, type-specific metadata)
• decode_entity_guid: Decode a base64-encoded entity GUID to reveal account ID, domain, entity type, and domain ID without an API call
• get_entity_tags: Get all tags for an entity by GUID
• add_tags_to_entity: Add or update key-value tags on an entity
• replace_tags_on_entity: Replace all tags on an entity (overwrites existing)
• delete_tags_from_entity: Remove tag keys from an entity
• delete_tag_values: Delete specific tag key-value pairs from an entity
• list_service_levels: List all SLIs/SLOs with compliance data and objectives
• get_service_level: Get full SLI definitions (event queries, objectives, time windows) for an entity
• create_service_level: Create a Service Level Indicator on an entity
• update_service_level: Update an SLI's name, description, event queries, or objectives
• delete_service_level: Delete an SLI by its SERVICE_LEVEL entity GUID
• list_synthetic_monitors: List all synthetic monitors with status, success rate, and location health
• get_synthetic_results: Get recent pass/fail check results per location for a specific monitor

Alert & Notification Management

• create_alert_policy: Create alert policies with incident preferences
• update_alert_policy: Update an existing alert policy
• delete_alert_policy: Delete an alert policy by ID
• create_nrql_condition: Create NRQL-based alert conditions
• update_nrql_condition: Update an existing NRQL alert condition
• delete_nrql_condition: Delete a NRQL alert condition by ID
• create_notification_destination: Set up notification endpoints (email, Slack, webhook, PagerDuty)
• delete_notification_destination: Delete a notification destination by ID
• create_notification_channel: Create notification channels
• delete_notification_channel: Delete a notification channel by ID
• create_workflow: Connect alerts to notifications with filtering
• update_workflow: Update a workflow's name, enabled state, channels, or issues filter
• delete_workflow: Delete a workflow by ID
• create_muting_rule: Create a muting rule to suppress alert notifications during scheduled windows
• list_muting_rules: List all muting rules with their conditions and schedules
• update_muting_rule: Update a muting rule's name, conditions, schedule, or enabled state
• delete_muting_rule: Delete a muting rule by ID
• list_alert_policies: List all alert policies
• list_alert_conditions: List alert conditions with optional filters by policy, name, or NRQL query
• list_notification_destinations: List all notification destinations
• list_notification_channels: List all notification channels
• list_workflows: List all alert workflows

MCP Resources

Access structured data through these MCP resources:

• newrelic://applications: Complete list of monitored applications
• newrelic://incidents/recent: Recent incidents and alert summary
• newrelic://dashboards: Dashboard metadata (name, GUID, created date, URL)
• newrelic://alerts/policies: Alert policies and configurations
• newrelic://alerts/conditions: Alert conditions across all policies
• newrelic://alerts/workflows: Workflow configurations and notifications

Architecture

Design

• Strategy Pattern: Tool handlers using pluggable strategy implementations
• Composition: NewRelicClient composes specialized sub-clients (monitoring, alerts, dashboards, entities) instead of using multiple inheritance
• Configuration: Hierarchical config (CLI > file > env vars) with validation
• Error Handling: Typed ApiError dataclass for consistent error propagation
• Pagination: Cursor-based pagination for NerdGraph queries (entity search, dashboards, alert policies, conditions, notification destinations/channels, workflows, service levels, synthetic monitors)
• Resilience: Bounded retry with backoff on HTTP 429/502/503/504, honoring Retry-After

Key Components

• NewRelicClient: Unified client composing all specialized sub-clients
• AlertsClient: Alert policies, conditions, and notification management
• DashboardsClient: Dashboard and widget operations
• EntitiesClient: Entity search, tagging, service levels, and synthetic monitors
• MonitoringClient: NRQL queries and performance monitoring
• ToolHandlers: Strategy-based dispatcher for MCP tool calls
• ResourceHandlers: MCP resource operations and data formatting

Docker Support

Build

docker build -t newrelic-mcp-server .

MCP Client Integration (Recommended)

The server speaks MCP over stdio, so your MCP client should launch the container itself with docker run -i --rm (interactive stdin, removed on exit):

{
  "mcpServers": {
    "newrelic": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "NEW_RELIC_API_KEY",
        "-e", "NEW_RELIC_ACCOUNT_ID",
        "newrelic-mcp-server"
      ],
      "env": {
        "NEW_RELIC_API_KEY": "your-api-key",
        "NEW_RELIC_ACCOUNT_ID": "your-account-id"
      }
    }
  }
}

A docker-compose.yml is included, but compose keeps an idle long-running container — since MCP clients spawn the server on demand, prefer the docker run -i --rm client config above. Compose is mainly useful for keeping a pre-built image and env wiring around during development.

Image Details

The Dockerfile is a single-stage build on python:3.11-slim that:

• installs locked dependencies with uv sync --frozen (dependency layer cached separately from source)
• copies the application source and installs the project
• runs as a non-root mcp user
• starts the stdio server via uv run python server.py (no ports exposed — communication is over stdin/stdout)

Development

Development Setup

# Install development dependencies
uv sync --dev

# Install pre-commit hooks
uv run pre-commit install

# Run quality checks
uv run ruff check .          # Linting
uv run ruff format .         # Formatting  
uv run mypy newrelic_mcp/    # Type checking
uv run pylint newrelic_mcp/  # Additional analysis

Code Quality

This project maintains high code quality with:

• Ruff: Fast linting and formatting
• MyPy: Static type checking
• Pylint: Additional code analysis
• Pre-commit hooks: Automated quality checks
• Comprehensive type annotations: Full type coverage

Testing

# Run all tests
uv run pytest tests/

# Run with verbose output
uv run pytest tests/ -v

For detailed development information, see DEVELOPMENT.md.

Example Usage

Complete Alert Setup Workflow

# 1. Create alert policy
create_alert_policy(name="High CPU Usage Policy")

# 2. Create NRQL condition  
create_nrql_condition(
    policy_id="policy-id-from-step-1",
    name="High CPU Alert",
    nrql_query="SELECT average(cpuPercent) FROM SystemSample",
    threshold=80
)

# 3. Create notification destination
create_notification_destination(
    name="Team Email",
    type="EMAIL", 
    properties={"email": "alerts@company.com"}
)

# 4. Create notification channel
create_notification_channel(
    name="CPU Alert Channel",
    destination_id="destination-id-from-step-3",
    type="EMAIL"
)

# 5. Create workflow
create_workflow(
    name="CPU Alert Workflow",
    channel_ids=["channel-id-from-step-4"]
)

Requirements

• Python: 3.11 or higher
• New Relic API Key: User API key (starts with NRAK- or NRAA-)
• New Relic Account: Valid account with appropriate permissions
• Dependencies: Managed automatically with uv or pip

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contributing

Contributions are welcome! Please:

1. Read DEVELOPMENT.md for setup instructions
2. Follow the established code style and quality standards
3. Add tests for new functionality
4. Update documentation as needed

Support

• Documentation: Check DEVELOPMENT.md for detailed guides
• Issues: Report bugs and feature requests via GitHub Issues
• New Relic API: Official New Relic API Documentation
• MCP Protocol: Model Context Protocol Specification