MCP Server

通过 MCP 协议将 Flashduty API 接入 AI 工具，在 Cursor、Claude 等客户端中实现智能化故障管理与自动化。

Flashduty MCP Server 是一个 Model Context Protocol (MCP) 服务端，将 Flashduty API 无缝接入支持 MCP 的 AI 工具（如 Cursor、Claude Desktop）。借助它，您可以让大模型直接查询故障、确认与关闭故障、检索协作空间与成员、校验通知模板，把故障管理与自动化能力嵌入 AI 工作流。

Flashduty MCP Server 底层基于 go-flashduty SDK 实现，所有工具均是对 Flashduty 开放 API 的薄封装。

​

适用场景

---

自动化故障流程

将 Flashduty 的故障创建、确认、关闭等操作交给 AI 编排，串联到您的运维工作流中。

数据提取与分析

让大模型按时间范围、状态、严重程度等条件检索故障、告警与变更记录并归纳分析。

构建 AI 运维工具

在自研 AI 应用中调用 Flashduty 能力，构建智能值守、故障复盘等场景。

模板校验与调试

在编辑通知模板时，实时校验渲染结果、查询可用变量与函数。

​

部署方式

---

Flashduty MCP Server 提供三种部署方式，您可以根据 MCP 客户端的能力与运行环境选择。

远程服务（推荐）

无需本地安装，直接连接官方远程实例 https://mcp.flashcat.cloud/mcp，使用 Authorization: Bearer 携带您的 APP Key 进行认证。这是最快的接入方式。

以 Cursor 为例，在 MCP 配置中添加：

{
  "mcpServers": {
    "flashduty": {
      "url": "https://mcp.flashcat.cloud/mcp",
      "headers": {
        "Authorization": "Bearer <your_flashduty_app_key>"
      }
    }
  }
}

远程服务仅支持 Streamable HTTP 传输（POST /mcp）。请参考您所用 MCP 客户端的文档，确认远程 MCP 服务的配置语法与位置。

Docker

在本地通过 Docker 运行，使用 FLASHDUTY_APP_KEY 环境变量认证，采用 stdio 传输。

{
  "mcpServers": {
    "flashduty": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "FLASHDUTY_APP_KEY",
        "registry.flashcat.cloud/public/flashduty-mcp-server"
      ],
      "env": {
        "FLASHDUTY_APP_KEY": "your_flashduty_app_key"
      }
    }
  }
}

源码构建

从 GitHub Releases 下载预编译版本，或在 cmd/flashduty-mcp-server 目录下用 go build 自行构建。APP Key 既可通过环境变量传入，也可通过命令行参数传入。

通过环境变量：

{
  "mcpServers": {
    "flashduty": {
      "command": "/path/to/flashduty-mcp-server",
      "args": ["stdio"],
      "env": {
        "FLASHDUTY_APP_KEY": "your_app_key_here"
      }
    }
  }
}

通过命令行参数：

{
  "mcpServers": {
    "flashduty": {
      "command": "/path/to/flashduty-mcp-server",
      "args": ["stdio", "--app-key", "your_app_key_here"]
    }
  }
}

​

认证与传输

---

项目	说明
认证（本地）	通过 FLASHDUTY_APP_KEY 环境变量或 --app-key 命令行参数提供 Flashduty APP Key。
认证（远程）	通过请求头 Authorization: Bearer <your_flashduty_app_key> 提供 APP Key。
Streamable HTTP	flashduty-mcp-server http，端点为 POST /mcp。官方远程实例为 https://mcp.flashcat.cloud/mcp。
stdio	flashduty-mcp-server stdio，用于 Cursor、Claude Desktop 等本地客户端。

服务端不支持旧版独立 SSE 传输（单独的 GET /sse 端点），对 GET 请求会返回 405 Method Not Allowed。Streamable HTTP 已按 MCP 规范在 POST 上完成流式响应，请直接使用它；若客户端仅支持旧版 SSE，请升级客户端或在本地改用 stdio。

​

配置项

---

Flashduty MCP Server 支持工具集裁剪、只读模式、输出格式等配置，以适配不同使用场景。本地部署可通过环境变量或命令行参数配置；远程服务可通过在 URL 上追加查询参数动态配置。

​

环境变量

字段	默认值	说明
FLASHDUTY_APP_KEY	-	Flashduty APP Key（必填）。
FLASHDUTY_TOOLSETS	全部工具集	以逗号分隔，指定启用的工具集（如 incidents,users,channels）；可用 all 启用全部。
FLASHDUTY_READ_ONLY	false	开启只读模式（1 或 true），仅保留查询类工具，禁止任何写操作。
FLASHDUTY_OUTPUT_FORMAT	json	工具结果输出格式，可选 json 或 toon。
FLASHDUTY_BASE_URL	https://api.flashcat.cloud	Flashduty API 的基础地址。

仅启用您需要的工具集，既能帮助大模型更准确地选择工具，也能减小上下文体积。开启只读模式可在数据分析、值守巡检等只需读取的场景下提升安全性。

Docker 示例：

docker run -i --rm \
  -e FLASHDUTY_APP_KEY=<your-app-key> \
  -e FLASHDUTY_TOOLSETS="incidents,users,channels" \
  -e FLASHDUTY_READ_ONLY=1 \
  registry.flashcat.cloud/public/flashduty-mcp-server

​

命令行参数

从源码构建并直接运行二进制时，可使用以下命令行参数（优先级高于同名环境变量）：

./flashduty-mcp-server stdio \
  --app-key your_app_key_here \
  --toolsets incidents,users,channels \
  --read-only \
  --output-format toon

• --app-key：Flashduty APP Key（等价于 FLASHDUTY_APP_KEY）。
• --toolsets：以逗号分隔的启用工具集列表。
• --read-only：开启只读模式。
• --output-format：工具结果输出格式（json 或 toon）。
• --base-url：Flashduty API 基础地址。

​

远程服务配置

使用官方远程实例时，可在 URL 上追加查询参数动态配置工具集与只读模式：

{
  "mcpServers": {
    "flashduty": {
      "url": "https://mcp.flashcat.cloud/mcp?toolsets=incidents,users&read_only=true",
      "headers": {
        "Authorization": "Bearer <your_flashduty_app_key>"
      }
    }
  }
}

​

输出格式（TOON）

服务端支持 TOON（Token-Oriented Object Notation）格式输出工具结果。对于字段统一的对象数组（如成员列表、故障列表），TOON 相比 JSON 可显著减少 30%-50% 的 Token 消耗，且现代大模型可直接解析。设置 FLASHDUTY_OUTPUT_FORMAT=toon（或 --output-format toon）即可启用。

​

工具集与工具

---

服务端共提供 8 个工具集、23 个工具，默认全部启用。下表为各工具集概览：

工具集	工具数	说明
incidents	8	故障全生命周期管理与查询
status_page	4	状态页（Status Page）管理
templates	4	通知模板校验与变量、函数查询
users	2	成员与团队查询
channels	2	协作空间与升级规则查询
alerts	1	告警原始事件查询
changes	1	变更记录查询
fields	1	自定义字段定义查询

工具集名称（incidents、status_page 等）为程序内部标识，配置时请保持英文原样。

各工具集包含的工具如下：

incidents — 故障生命周期管理（8 个工具）

工具	说明
query_incidents	按 ID、短号、时间范围、状态、严重程度、协作空间或自由文本查询故障，返回故障列表及每条故障的告警总数。
query_incident_timeline	查询故障的时间线事件（创建、分派、确认、解决、通知等）。每条事件包含 created_at（RFC3339 格式）和 creator_id（操作者数字 ID，0 表示系统自动操作）；如需将 creator_id 转换为显示名称，可调用 query_members。
query_incident_alerts	查询故障关联的告警，返回标题、严重程度、状态与标签。
create_incident	创建故障，指定标题与严重程度，可选分派到协作空间或响应人。
update_incident	更新故障的内置字段（标题、描述、严重程度、影响、根因、解决方案）及自定义字段，仅更新提供的字段。
ack_incident	确认故障，将状态从「已触发」转为「处理中」。
close_incident	关闭（解决）故障，将状态转为「已关闭」。
list_similar_incidents	查找历史相似故障，用于复盘既往处置方案、识别重复问题。

query_incidents 参数说明

参数	类型	说明
incident_ids	string	逗号分隔的完整故障 ID，用于直接查找。提供此参数时其他过滤条件将被忽略。
nums	string	逗号分隔的短号（6 位数字，即 UI 中显示的短 ID，如 311510）。短号匹配在 since/until 时间窗口内进行，后端单次查询上限约 30 天；超过 30 天的历史故障需改用完整 incident_id 查询。
since	string	查询起始时间（见下方时间格式说明）。
until	string	查询截止时间（见下方时间格式说明）。
progress	string	按状态过滤，可选：Triggered、Processing、Closed，逗号分隔支持多选。
severity	string	按严重程度过滤，可选：Info、Warning、Critical。
channel_ids	string	逗号分隔的协作空间 ID。
query	string	自由文本搜索（标题、标签、内容）。
limit	number	返回条数，默认 20，最大 100。

since / until 时间窗口行为

• 两者均省略：默认查询最近 30 天（适合查询当前未关闭故障）。
• 仅提供 since：从该时间查询到当前时刻。
• 仅提供 until：不允许，返回错误（since 为必填，或两者都省略）。
• 同时提供：查询指定时间段，后端硬上限约 30 天。

时间格式：支持以下任意格式：

• 相对时长：30d、24h、168h（表示距今多久之前）
• RFC3339 含时区：2026-04-01T10:00:00+08:00 或 2026-04-01T10:00:00Z（SDK 返回的时间戳可直接用作过滤参数）
• 日期：2026-04-01（解析为本地时间零点）
• 日期时间：2026-04-01 10:00:00 或 2026-04-01T10:00:00（本地时间）
• Unix 时间戳：1712000000

status_page — 状态页管理（4 个工具）

工具	说明
query_status_pages	查询状态页及其完整配置。
list_status_changes	列出状态页上当前进行中（未关闭）的变更事件（故障或维护）。仅返回活跃事件，已解决或已完成的历史事件不在返回范围内。
create_status_incident	在状态页上创建事件。
create_change_timeline	为状态页变更追加时间线更新。

templates — 通知模板（4 个工具）

工具	说明
get_preset_template	获取指定协作空间的预置（默认）通知模板，返回可作为定制起点的 Go 模板代码。
validate_template	校验通知模板：解析并以故障数据渲染，返回渲染预览、校验状态与大小信息，支持 mock 数据或基于 incident_id 的真实预览。
list_template_variables	列出通知模板中可用的所有变量，返回带类型、说明与示例值的变量结构。
list_template_functions	列出通知模板中可用的所有函数，含 Flashduty 自定义函数与常用 Sprig 函数。

users — 成员与团队查询（2 个工具）

工具	说明
query_members	查询成员，支持可选过滤条件。
query_teams	查询团队及其成员详情。

channels — 协作空间与升级规则（2 个工具）

工具	说明
query_channels	查询协作空间，返回团队、创建者等增强数据。
query_escalation_rules	查询某个协作空间的升级规则。

alerts — 告警事件查询（1 个工具）

工具	说明
query_alert_events	查询单条告警的原始事件，返回产生该告警的上游事件流（如每次 Prometheus 触发）。

changes — 变更记录查询（1 个工具）

工具	说明
query_changes	按过滤条件查询变更记录。

fields — 自定义字段（1 个工具）

工具	说明
query_fields	查询自定义字段定义。

​

相关资源

---

go-flashduty SDK

MCP Server 底层依赖的 Go SDK，覆盖 Flashduty 全部开放 API。

GitHub 仓库

查看源码、Release 与问题反馈。