FlashDuty MCP Server

Features | Getting Started | Configuration | Tools | Development

Features

A Model Context Protocol (MCP) server for FlashDuty incident management.

• Incident Management: List, create, acknowledge, resolve, reopen, snooze, and comment on incidents
• Alert Management: List, get details, and close alerts
• Collaboration Spaces: List and inspect channels (collaboration spaces)
• Team & Member Lookup: List teams and members
• On-call Schedules: Query on-call schedules by team
• Incident Statistics: MTTA, MTTR, counts, ack rate, and noise reduction metrics
• Incident Timeline: View event feed (comments, acks, resolves, escalations, notifications)
• Incident-Alert Association: See which alerts belong to a given incident
• Brief Mode: Reduce response size for LLM token limits by returning only key fields
• Advanced Filtering: Filter by channel, responder, acknowledger, creator, labels, and severity
• Security Controls: read_only mode to disable all write operations
• Dual Transport: Stdio mode for MCP client integration or HTTP/SSE mode for network access
• Cross-platform: Native binaries for Linux, macOS, Windows (amd64/arm64), npm package, and Docker images

Getting Started

Requirements

• A FlashDuty API app key (from FlashDuty Console -> Personal Settings -> API Keys)

Claude Code

claude mcp add flashduty -- npx @futuretea/flashduty-mcp-server@latest \
  --app-key YOUR_APP_KEY

VS Code / Cursor

Add to .vscode/mcp.json or ~/.cursor/mcp.json:

{
  "servers": {
    "flashduty": {
      "command": "npx",
      "args": [
        "-y",
        "@futuretea/flashduty-mcp-server@latest",
        "--app-key",
        "YOUR_APP_KEY"
      ]
    }
  }
}

Docker

Stdio mode:

docker run --rm -i ghcr.io/futuretea/flashduty-mcp-server:latest \
  --app-key YOUR_APP_KEY

HTTP/SSE mode:

docker run --rm -p 8080:8080 ghcr.io/futuretea/flashduty-mcp-server:latest \
  --port 8080 --app-key YOUR_APP_KEY

Configuration

Configuration can be set via CLI flags, environment variables, or a config file.

Priority (highest to lowest):

1. Command-line flags
2. Environment variables (prefix: FLASHDUTY_MCP_)
3. Configuration file
4. Default values

CLI Options

npx @futuretea/flashduty-mcp-server@latest --help

Option	Description	Default
--config	Config file path (YAML)
--port	Port for HTTP/SSE mode (0 = stdio mode)	0
--sse-base-url	Public base URL for SSE endpoint
--log-level	Log level (0-9)	5
--app-key	FlashDuty API app key (required)
--base-url	FlashDuty API base URL	https://api.flashcat.cloud
--read-only	Disable write operations	false
--enabled-tools	Specific tools to enable
--disabled-tools	Specific tools to disable

Configuration File

Create config.yaml:

port: 0  # 0 for stdio, or set a port like 8080 for HTTP/SSE

log_level: 5

# Get the app_key from your FlashDuty account:
# https://console.flashcat.cloud -> Personal Settings -> API Keys
app_key: your-app-key-here

# base_url: https://api.flashcat.cloud

read_only: false  # Set to true to disable write operations

# enabled_tools: []
# disabled_tools: []

Environment Variables

Use FLASHDUTY_MCP_ prefix with underscores:

FLASHDUTY_MCP_PORT=8080
FLASHDUTY_MCP_APP_KEY=your-key
FLASHDUTY_MCP_READ_ONLY=false
FLASHDUTY_MCP_LOG_LEVEL=5

HTTP/SSE Mode

Run with a port number for network access:

flashduty-mcp-server --port 8080 --app-key YOUR_APP_KEY

Endpoints:

• /healthz - Health check
• /mcp - Streamable HTTP endpoint
• /sse - Server-Sent Events endpoint
• /message - Message endpoint for SSE clients

With a public URL behind a proxy:

flashduty-mcp-server --port 8080 \
  --sse-base-url https://your-domain.com:8080 \
  --app-key YOUR_APP_KEY

Tools

Use --enabled-tools / --disabled-tools for fine-grained control.

Use --read-only to disable all write operations (create, acknowledge, resolve, reopen, snooze, comment, close).

Incident Tools

List incidents from FlashDuty. Use brief=true to reduce response size (recommended for initial queries).

Parameter	Type	Required	Description
time_range	string	No	Relative time range: 1h, 24h, 7d, 30d, 1w, 6M, or last_day, last_week. Alternative to start_time+end_time.
start_time	number	Conditional	Search interval start time in unix seconds. Required if time_range is not set.
end_time	number	Conditional	Search interval end time in unix seconds. Required if time_range is not set.
brief	boolean	No	If true, return only key fields to reduce data volume.
progress	string	No	Filter by progress: Triggered, Processing, Closed, or comma-separated.
incident_severity	string	No	Filter by severity: Critical, Warning, Info, or comma-separated.
title	string	No	Filter by title. Supports exact, regex (/pattern/), and wildcards (*, ?).
channel_ids	integer[]	No	Filter by collaboration space IDs.
responder_ids	integer[]	No	Filter by responder person IDs.
acker_ids	integer[]	No	Filter by acknowledger person IDs.
creator_ids	integer[]	No	Filter by creator person IDs. 0 = system-generated.
labels	object	No	Filter by labels (key -> array of values).
limit	number	No	Page size (1-100, default 20).
p	number	No	Page number starting from 1.

Get detailed information about a specific incident.

Parameter	Type	Required	Description
incident_id	string	Yes	The incident ID.

Create a new incident in FlashDuty. Disabled when read_only=true.

Parameter	Type	Required	Description
title	string	Yes	Incident title.
incident_severity	string	Yes	Severity: Critical, Warning, or Info.
description	string	No	Incident description (plain text or markdown).
channel_id	number	No	Collaboration space ID.

Acknowledge (claim) one or more incidents. Disabled when read_only=true.

Parameter	Type	Required	Description
incident_ids	string[]	Yes	List of incident IDs to acknowledge.

Resolve (close) one or more incidents. Disabled when read_only=true.

Parameter	Type	Required	Description
incident_ids	string[]	Yes	List of incident IDs to resolve.
root_cause	string	No	Root cause of the incident.
resolution	string	No	How the incident was resolved.

Reopen one or more previously resolved incidents. Disabled when read_only=true.

Parameter	Type	Required	Description
incident_ids	string[]	Yes	List of incident IDs to reopen.
reason	string	Yes	Reason for reopening.

Snooze (temporarily mute) one or more incidents. Disabled when read_only=true.

Parameter	Type	Required	Description
incident_ids	string[]	Yes	List of incident IDs to snooze.
minutes	number	Yes	Minutes to snooze (1-1440).

Add a comment to one or more incidents. Disabled when read_only=true.

Parameter	Type	Required	Description
incident_ids	string[]	Yes	List of incident IDs to comment on.
comment	string	Yes	Comment content (1-500 characters).

Update an incident's details. At least one field besides incident_id must be provided. Disabled when read_only=true.

Parameter	Type	Required	Description
incident_id	string	Yes	The incident ID to update.
title	string	No	New incident title.
description	string	No	New incident description. Supports markdown.
incident_severity	string	No	New severity: Critical, Warning, or Info.
impact	string	No	Impact description of the incident.
root_cause	string	No	Root cause of the incident.
resolution	string	No	Resolution description of the incident.

Assign one or more incidents to specific persons or an escalation rule. Disabled when read_only=true.

Parameter	Type	Required	Description
incident_ids	string[]	Yes	List of incident IDs to assign.
type	string	No	Assignment type: assign (direct) or escalateRule. Default: assign.
person_ids	integer[]	No	List of person IDs to assign to (when type is assign).
escalate_rule_id	number	No	Escalation rule ID (when type is escalateRule).

Alert Tools

List alerts from FlashDuty. Use brief=true to reduce response size.

Parameter	Type	Required	Description
time_range	string	No	Relative time range: 1h, 24h, 7d, 30d, 1w, 6M, or last_day, last_week. Alternative to start_time+end_time.
start_time	number	Conditional	Search interval start time in unix seconds. Required if time_range is not set.
end_time	number	Conditional	Search interval end time in unix seconds. Required if time_range is not set.
brief	boolean	No	If true, return only key fields to reduce data volume.
alert_severity	string	No	Filter by severity: Critical, Warning, Info, or comma-separated.
title	string	No	Filter by title. Supports exact, regex, and wildcards.
is_active	boolean	No	Filter by active status.
channel_ids	integer[]	No	Filter by collaboration space IDs.
labels	object	No	Filter by labels (key -> array of values).
limit	number	No	Page size (1-100, default 20).
p	number	No	Page number starting from 1.

Get detailed information about a specific alert.

Parameter	Type	Required	Description
alert_id	string	Yes	The alert ID.

Close one or more alerts. Disabled when read_only=true.

Parameter	Type	Required	Description
alert_ids	string[]	Yes	List of alert IDs to close.

Channel Tools

List collaboration spaces (channels).

Parameter	Type	Required	Description
query	string	No	Search keyword to match channel name and description.
limit	number	No	Page size.
p	number	No	Page number starting from 1.

Get detailed information about a specific channel.

Parameter	Type	Required	Description
channel_id	number	Yes	The channel ID.

Team & Member Tools

List teams from FlashDuty.

Parameter	Type	Required	Description
query	string	No	Search keyword to match team name and description.
limit	number	No	Page size.
p	number	No	Page number starting from 1.

List members from FlashDuty.

Parameter	Type	Required	Description
query	string	No	Search keyword to match name and email. Phone number triggers strict match.
limit	number	No	Page size.
p	number	No	Page number starting from 1.

Schedule Tools

List on-call schedules.

Parameter	Type	Required	Description
team_ids	integer[]	Yes	List of team IDs to filter schedules.
query	string	No	Search keyword to match schedule name.
limit	number	No	Page size.
p	number	No	Page number starting from 1.

Insight Tools

Get aggregated incident statistics (MTTA, MTTR, counts, ack rate, noise reduction).

Parameter	Type	Required	Description
time_range	string	No	Relative time range: 1h, 24h, 7d, 30d, 1w, 6M, or last_day, last_week. Alternative to start_time+end_time.
start_time	number	Conditional	Start time in unix seconds. Required if time_range is not set.
end_time	number	Conditional	End time in unix seconds (max span 6 months). Required if time_range is not set.
channel_ids	integer[]	No	Filter by collaboration space IDs.
team_ids	integer[]	No	Filter by team IDs.
severities	string[]	No	Filter by severities: Critical, Warning, Info.
aggregate_unit	string	No	Time aggregation: day, week, or month.
query	string	No	Filter by incident title (fuzzy match).
labels	object	No	Filter by labels as key-value pairs.

Get the timeline (feed) of an incident.

Parameter	Type	Required	Description
incident_id	string	Yes	The incident ID.
types	string[]	No	Filter by event types (e.g., i_comm, i_ack, i_rslv, i_notify).
limit	number	No	Page size.
p	number	No	Page number starting from 1.

List alerts associated with a specific incident.

Parameter	Type	Required	Description
incident_id	string	Yes	The incident ID.
is_active	boolean	No	Filter by active status.
limit	number	No	Page size (max 1000, default 1000).
p	number	No	Page number starting from 1.

Similar Incidents Tools

Find similar historical incidents for a given incident. Useful for pattern analysis and diagnosis.

Parameter	Type	Required	Description
incident_id	string	Yes	The incident ID to find similar incidents for.
limit	number	No	Maximum number of similar incidents to return (max 20).

Change Tools

Query deployment/change events from FlashDuty. Useful for correlating incidents with recent deployments.

Parameter	Type	Required	Description
time_range	string	No	Relative time range: 1h, 24h, 7d, 30d, 1w, 6M, or last_day, last_week. Alternative to start_time+end_time.
start_time	number	No	Start time in unix seconds.
end_time	number	No	End time in unix seconds.
query	string	No	Search keyword to filter changes.
channel_ids	integer[]	No	Filter by collaboration space IDs.
integration_ids	integer[]	No	Filter by integration IDs.
order_by	string	No	Field to order by (e.g., start_time).
asc	boolean	No	Sort ascending if true, descending if false.
include_events	boolean	No	Include change events in the response.
limit	number	No	Page size (1-100, default 20).
p	number	No	Page number starting from 1.

Escalation Tools

Query escalation rules for a collaboration space. Returns the escalation policy configuration.

Parameter	Type	Required	Description
channel_id	number	Yes	The collaboration space (channel) ID.

Custom Field Tools

Query custom field definitions from FlashDuty. Returns all configured custom fields for incidents. No parameters required.

Development

Build

make build

Test

go test ./...

Lint

make lint

Run with mcp-inspector

npx @modelcontextprotocol/inspector@latest -- npx @futuretea/flashduty-mcp-server@latest

Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.

License

Apache-2.0