Nightingale MCP Server

English | 中文

An MCP (Model Context Protocol) server for Nightingale monitoring system. This server enables AI assistants to interact with Nightingale APIs for alert management, monitoring, and observability tasks through natural language.

Compatibility

• Nightingale: v8.0.0+

Key Use Cases

• Alert Management: Query active and historical alerts, view alert rules and subscriptions
• Target Monitoring: Browse and search monitored hosts/targets, analyze target status
• Incident Response: Create and manage alert mutes, notification rules, and event pipelines
• Team Collaboration: Query users, teams, and business groups

Quick Start

1. Get an API Token

1. Make sure HTTP.TokenAuth is enabled in config.toml:

  [HTTP.TokenAuth]
  Enable = true

2. Log in to your Nightingale web interface
3. Navigate to Personal Settings > Profile > Token Management
4. Create a new token with appropriate permissions

Security Note: Store your API token securely. Never commit tokens to version control. Use environment variables or secure secret management.

2. Configure MCP Client

Cursor (stdio mode, default)

Add to your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "nightingale": {
      "command": "npx",
      "args": ["-y", "@n9e/n9e-mcp-server", "stdio"],
      "env": {
        "N9E_TOKEN": "your-api-token",
        "N9E_BASE_URL": "http://your-n9e-server:17000"
      }
    }
  }
}

HTTP mode (optional)

To run the server over HTTP (MCP streamable transport, JSON only, no SSE), start the server with the http subcommand.

Shared vs non-shared (HTTP only):

• --shared=false (default): Token and base URL may be omitted at startup. Each client can provide X-User-Token and X-N9e-Base-Url in mcp.json so everyone uses their own Nightingale identity or instance. If you do set N9E_TOKEN and N9E_BASE_URL at startup, they act as defaults and clients can still override via headers.
• --shared=true: Startup must set N9E_TOKEN and N9E_BASE_URL. The server uses only this config; client headers X-User-Token and X-N9e-Base-Url are ignored. Use this when the MCP server is a shared org service and users must not override credentials.

# Non-shared: users supply token/URL in mcp.json (or you set defaults at startup)
n9e-mcp-server http --listen :8080

# Shared: one token/URL for all; require at startup, ignore client headers
N9E_TOKEN=xxx N9E_BASE_URL=https://n9e.example.com n9e-mcp-server http --listen :8080 --shared

Cursor: connect to HTTP server

If the server is already running in HTTP mode (e.g. on http://localhost:8080), add a URL-based entry to ~/.cursor/mcp.json (no command/args; Cursor will use the streamable HTTP transport).

Token: You can use either source; you do not need to pass token in mcp.json if the server was started with N9E_TOKEN.

1. Server startup only – Set N9E_TOKEN when starting the server (e.g. N9E_TOKEN=xxx ./n9e-mcp-server http). All clients will use this token; no headers needed in Cursor.
2. Client headers (optional) – The client can send:
   • X-User-Token: use this token for N9e API calls instead of the startup token.
   • X-N9e-Base-Url: use this URL as the Nightingale API base (e.g. https://n9e.other-env.com) instead of the server's N9E_BASE_URL. So each user can point to a different Nightingale instance or use their own token (or both).

Example when the server was started with N9E_TOKEN (no header needed in Cursor):

{
  "mcpServers": {
    "nightingale": {
      "url": "http://localhost:8080"
    }
  }
}

Example when passing token and/or base URL from Cursor (e.g. shared server, or different Nightingale instance):

{
  "mcpServers": {
    "nightingale": {
      "url": "http://localhost:8080",
      "headers": {
        "X-User-Token": "your-nightingale-api-token",
        "X-N9e-Base-Url": "http://your-n9e-server:17000"
      }
    }
  }
}

You can omit either header: only X-User-Token, or only X-N9e-Base-Url, or both. The server falls back to startup N9E_TOKEN and N9E_BASE_URL when a header is not set. If the server was started with --shared, these headers are ignored and you must not rely on them.

If your HTTP server is behind a gateway that requires its own auth, add those headers as well (e.g. Authorization: Bearer your-gateway-token). The server uses the X-User-Token header only for calling the Nightingale API.

Docker

The official code uses the stdio protocol by default for inter-process communication. If you need to integrate with web-based LLM orchestration platforms like Dify or FastGPT that only support network calls (HTTP/SSE), we recommend using the provided Docker Compose solution. This deployment automatically introduces the mcp-proxy bridge to enable network protocol support.

Deployment Steps:

1. Clone this repository:

   git clone https://github.com/n9e/n9e-mcp-server.git
   cd n9e-mcp-server/docker
   

2. Modify the configuration in docker-compose.yml:

   • MCP_VERSION: (Optional) Used by the default Dockerfile to install @n9e/n9e-mcp-server from NPM during image build. Set this explicitly to latest or to a concrete version such as 0.1.1. Do not leave it blank.
   • N9E_BASE_URL: Replace with your actual Nightingale API URL.
   • N9E_TOKEN: Replace with your generated API Token.

3. Start the service:

   # By default, it will install the specified version via NPM and start
   docker compose up -d --build
   

4. Configure the MCP plugin in Dify:

   • Connection Type: Streamable HTTP (SSE)
   • URL: http://<Your-Server-IP>:8082/sse

Developer Note: If you have modified the source code and wish to build a local test image, change the dockerfile field in docker-compose.yml to docker/Dockerfile.source. This will copy the repository source into the image, build the Go server locally, and still start the server through the mcp-proxy bridge.

3. Restart Cursor or Other Client Processes to Use

Available Tools

Toolset	Tool	Description
alerts	list_active_alerts	List currently firing alerts with optional filters
alerts	get_active_alert	Get details of a specific active alert by event ID
alerts	list_history_alerts	List historical alerts with optional filters
alerts	get_history_alert	Get details of a specific historical alert
alerts	list_alert_rules	List alert rules for a business group
alerts	get_alert_rule	Get details of a specific alert rule
targets	list_targets	List monitored hosts/targets with optional filters
datasource	list_datasources	List all available datasources
mutes	list_mutes	List alert mutes for a business group
mutes	get_mute	Get details of a specific alert mute
mutes	create_mute	Create a new alert mute/silence rule
mutes	update_mute	Update an existing alert mute/silence rule
notify_rules	list_notify_rules	List all notification rules
notify_rules	get_notify_rule	Get details of a specific notification rule
alert_subscribes	list_alert_subscribes	List alert subscriptions for a business group
alert_subscribes	list_alert_subscribes_by_gids	List subscriptions across multiple business groups
alert_subscribes	get_alert_subscribe	Get details of a specific subscription
event_pipelines	list_event_pipelines	List all event pipelines/workflows
event_pipelines	get_event_pipeline	Get details of a specific event pipeline
event_pipelines	list_event_pipeline_executions	List execution records for a specific pipeline
event_pipelines	list_all_event_pipeline_executions	List all execution records across all pipelines
event_pipelines	get_event_pipeline_execution	Get details of a specific execution
users	list_users	List users with optional filters
users	get_user	Get details of a specific user
users	list_user_groups	List user groups/teams
users	get_user_group	Get details of a user group including members
busi_groups	list_busi_groups	List business groups accessible to the current user

Example Prompts

Once configured, you can interact with Nightingale using natural language:

• "Show me all critical alerts from the last 24 hours"
• "What alerts are currently firing?"
• "List all monitored targets that have been down for more than 5 minutes"
• "What alert rules are configured in business group 1?"
• "Create a mute rule for service=api alerts for the next 2 hours due to maintenance"
• "Show me the event pipeline execution history"
• "Who are the members of the ops team?"

Configuration

Modes

• stdio (default): MCP over stdin/stdout. Use with Cursor and other clients that spawn the server process.
• http: MCP over HTTP using the streamable transport (JSON request/response only, no SSE). Use n9e-mcp-server http and connect with a client that supports streamable HTTP (e.g. StreamableClientTransport).

Environment Variables

Variable	Flag	Description	Default
N9E_TOKEN	--token	Nightingale API token (required)	-
N9E_BASE_URL	--base-url	Nightingale API base URL	http://localhost:17000
N9E_READ_ONLY	--read-only	Disable write operations	false
N9E_TOOLSETS	--toolsets	Enabled toolsets (comma-separated)	all
N9E_LISTEN	--listen	HTTP mode: listen address	:8080
N9E_SESSION_TIMEOUT	--session-timeout	HTTP mode: idle session timeout (0 = no timeout)	0

Toolsets

By default, all toolsets are enabled. You can use the --toolsets flag or N9E_TOOLSETS environment variable to enable only the toolsets you need, reducing the number of tools exposed to the AI assistant and saving context window tokens.

Available toolsets: alerts, targets, datasource, mutes, busi_groups, notify_rules, alert_subscribes, event_pipelines, users

For example, to enable only alert and target related tools:

{
  "mcpServers": {
    "nightingale": {
      "command": "npx",
      "args": ["-y", "@n9e/n9e-mcp-server", "stdio"],
      "env": {
        "N9E_TOKEN": "your-api-token",
        "N9E_BASE_URL": "http://your-n9e-server:17000",
        "N9E_TOOLSETS": "alerts,targets"
      }
    }
  }
}

License

Apache License 2.0

Related Projects

• Nightingale - The enterprise-level cloud-native monitoring system
• MCP Go SDK - Official MCP SDK for Go
• MCP Specification - Model Context Protocol specification