Jira Alerts (JSM Operations)

Jira Alerts MCP

从你的 Agent 中查明是什么在触发你的告警，以及当前由谁值班。

这是一个适用于 Jira Service Management Operations 的 MCP 服务——它是取代 Opsgenie 的告警管理界面，也是其他 Jira MCP 服务都未涵盖的领域。

搜索告警并查看其备注和活动时间线；确认、关闭、添加注释并添加响应人员；还可查询当前和下一位值班人员。 共 12 个工具，其中 4 个用于写入。

演示

在一个会话中，针对一个运行中的 JSM 站点提出三个问题：当前由谁值班、有哪些未关闭的告警，以及确认哪些告警。特别留意最后一个回答——Agent 会确认确认操作确实已生效（ack landed 16:38:00.577Z），而不是假设操作成功。这就是此服务为你处理的内容中所述的异步写入行为。

快速开始

你需要： Node ≥ 24，以及启用了 JSM Operations 的 Atlassian Cloud 站点。 无需克隆或构建——你的 MCP 客户端会运行已发布的软件包。

1. 查找你的 cloud id。 登录站点后打开此地址：

https://<your-site>.atlassian.net/_edge/tenant_info

它会返回一行内容——{"cloudId":"..."}——这个 UUID 就是 JSM_CLOUD_ID 所需的值。如果你不想依赖该接口，也可以在 admin.atlassian.com → Apps → Sites → 你的站点 的 URL 中找到 /s/ 后面的那段内容作为 cloud id。

2. 创建 API 令牌，网址： id.atlassian.com。

3. 添加服务。

Claude Code：

claude mcp add jira-alerts-mcp \
  --scope user \
  --env JSM_CLOUD_ID='your-cloud-id' \
  --env JSM_EMAIL='[email protected]' \
  --env JSM_API_TOKEN="${JSM_API_TOKEN}" \
  --env JSM_TOOLSETS='all' \
  -- npx -y jira-alerts-mcp

JSM_TOOLSETS=all 会注册每个已验证的工具集，共 82 个工具，而不是 responder 默认提供的 28 个，并会额外启用排班、团队、维护窗口和路由功能。 你可以删掉这一行以从精简配置开始；all 并非可能涵盖范围最广的选项，因为仍需按名称显式启用三个隔离的功能族。有关每个工具集的覆盖范围，以及为什么工具列表更大并不一定更好，请参阅选择工具集。

--scope user 会将服务注册到你的整个账户，而不只是你运行命令时所在的目录。对于告警服务，这正是你需要的——你会希望它出现在每个会话中。不加此标志时，claude mcp add 默认使用 local 范围，服务只会在该目录中可用。

Claude Desktop： 请通过应用打开配置，而不是手动查找——点击菜单栏中的 Claude 菜单（不是窗口内的设置）→ Settings → Developer → Edit Config。如果文件不存在，这会创建该文件：

{
  "mcpServers": {
    "jira-alerts-mcp": {
      "command": "npx",
      "args": ["-y", "jira-alerts-mcp"],
      "env": {
        "JSM_CLOUD_ID": "your-cloud-id",
        "JSM_EMAIL": "[email protected]",
        "JSM_API_TOKEN": "your-api-token",
        "JSM_TOOLSETS": "all"
      }
    }
  }
}

mcpServers 是一个顶层键，文件中会包含你配置的所有服务。如果文件中已有 mcpServers 块，请在其中添加 jira-alerts-mcp 作为另一项——将上面的整个块粘贴并覆盖文件，会替换掉文件中原有的内容。 然后彻底退出 Claude Desktop 并重新打开——该文件只会在启动时读取，关闭窗口并不等于退出。之后，该服务会显示在消息编辑器的连接器面板中。

大多数其他 MCP 客户端也接受相同的 JSON 结构。这里无需选择作用范围——claude_desktop_config.json 已经是按用户配置的，作用范围与 CLI 中的 --scope user 相同。

4. 检查是否正常工作。 让你的 Agent 列出已打开的告警。这会运行 jsm_list_alerts，该工具不需要任何 id，并可确认你的凭据以及 read:ops-alert 作用范围；十四个工具中有九个共用此作用范围。

然后询问当前由谁值班，这会运行 jsm_list_schedules。这是一次单独的检查，因为查询排班需要 read:ops-config——如果告警查询正常，但排班查询返回 401，那并不意味着你的令牌有问题；请参阅下方的所需作用范围。

有几点容易让人困惑：使用 claude mcp add 时，服务名称是第一个位置参数，必须放在所有标志之前；npx 中的 -y 会跳过安装提示，而 MCP 客户端无法回答该提示；在 zsh 中，${VAR} 需要加引号。添加服务时如果没有指定 --scope user，它只会在添加时所在的目录中生效，在其他地方都不可见，而且不会给出任何说明缺失原因的错误——如果服务似乎消失了，请先在另一个目录中运行 claude mcp list，再进行其他操作。对于通过 GUI 启动的会话，令牌必须放在配置本身的 env 块中——shell 环境不会被继承，因此上面的 JSON 将凭据直接写在其中。

如果服务始终没有显示在 Claude Desktop 中，几乎所有情况都由以下两个原因造成，而且它们都不会自行提示：

• npx 不在 PATH 中。 GUI 应用由窗口管理器启动，而不是由 shell 启动，因此通过 nvm 安装的 Node 通常不会被它识别。将 "command" 设为 which node 返回的绝对路径，并让 "args" 指向已安装的 dist/index.js，或者在系统范围内安装 Node。低于 24 的 Node 即使能被找到，也会以 EBADENGINE 报错，而不是给出易读的错误信息。
• 服务在启动期间退出。 凭据会在握手前验证，因此错误的云端 id 或令牌会使服务立即停止——而且由于 stdout 是协议通道，该消息只会发送到 stderr。Claude Desktop 会将日志保存在 ~/Library/Logs/Claude/mcp-server-jira-alerts-mcp.log（Windows：%APPDATA%\Claude\logs\），文件名取自你在 mcpServers 下使用的键。查找 Startup failed:，后面会准确说明问题所在。

git clone https://github.com/rrvrs/jira-alerts-mcp.git
cd jira-alerts-mcp
npm install
npm run build

  -- node /absolute/path/to/jira-alerts-mcp/dist/index.js

配置

凭据会在启动时验证，因此错误配置会立即失败并给出可操作的提示，而不是等到首次调用工具时才失败。

.env.example 列出了这些变量供参考。服务本身不会读取 .env——MCP 服务由客户端启动，环境由客户端管理。可将此文件用作客户端 env 块的检查清单，也可以在本地开发时使用 set -a; source .env; set +a。

凭据能做什么、不能做什么

两种身份验证方式并不等同，而 Atlassian 的文档并未说明其中的区别。以下信息于 2026-09-05 在实际租户上验证：

删除权限范围按令牌授予，而非按身份验证方式授予。 同一账户的两个 Atlassian 账户 API 令牌表现不同：一个令牌的每次 DELETE 请求都遭到拒绝，返回 401 Unauthorized; scope does not match——凭据有效，但缺少授权；另一个令牌则完成了整组操作。因此，删除操作返回 401 并不意味着应放弃使用 JSM_EMAIL + JSM_API_TOKEN。请重新签发包含删除权限范围的令牌，或者提供已获授 delete:ops-alert:jira-service-management 权限的 3LO 或 Forge OAuth 令牌作为 JSM_OAUTH_TOKEN。401 处理程序会明确说明这一点，因此模型会报告该问题，而不会重试。

依赖删除权限的告警工具包括 jsm_delete_alert · jsm_delete_alert_note · jsm_remove_alert_tags · jsm_remove_alert_extra_properties · jsm_delete_alert_attachment。

告警附件端点受到双重限制。 API 自身的 OpenAPI 文档未为这些端点映射任何 OAuth 权限范围，因此缺少删除权限范围的令牌会在网关处被拒绝，并返回同样直白的 scope does not match——看起来像是身份验证走进了死胡同，但实际并非如此。权限范围完整的令牌可以访问 API，但随后会收到 Feature not available in your plan。对于不支持附件的站点套餐，没有任何令牌能启用附件，因此现在附件被单独放在隔离的 attachments 工具集中，没有任何配置会加载该工具集。处理程序会将套餐限制报告为套餐限制，而不是让你去扩大令牌权限范围。

有些操作取决于你的 JSM 套餐，而非权限范围。 在 Standard 租户中，暂停、分配和自定义操作会被接受，但随后会在带外失败，并返回 Your account plan does not support …。请求格式正确；限制来自套餐。这正是写入操作采用异步处理的原因，也说明了 jsm_get_request_status 为何重要——这三种操作的即时响应都是成功回执。

已验证和未验证的内容

此服务中的每个工具在发布前都经过了真实 Jira Service Management 站点的测试。配置文件可以加载的每个工具都确实成功运行——这是不可变条件，并且有测试强制执行：标记为未验证的工具集不能出现在配置文件中。

有三个工具集无法验证，因此它们以隔离状态随附，而不是被移除。没有证据表明它们有任何问题；只是无法在当时可用的站点上进行测试，而对于未屏蔽这些功能的站点，代码很可能是正确的。

如需启用其中一个，只需将其名称与其他所需工具集一并列出：

"env": { "JSM_TOOLSETS": "all,heartbeats" }

jsm_list_capabilities 在运行时也会报告相同信息，因此，当助手被问到“能否创建心跳？”时，它会告知对方该工具集存在但未启用、如何启用，以及该工具集从未被证实可用，而不是自行猜测。

有两个工具集在 2.0.0 版本中被移除，而非隔离。 告警策略（11 个工具）和自定义用户角色（6 个工具）在两组不同的凭据下都返回了 403 You are not authorized，其中一组凭据持有 Jira ADMINISTER 权限。自定义用户角色是 Opsgenie 的 Enterprise 功能，而策略遭拒看起来也是同类限制。仅凭代码能成功编译这一点作为依据，却要随附 17 个工具并增加工具列表负担，并不值得，因此它们已被移除。如果你的站点支持这些功能并希望恢复它们，请提交 issue——相关代码仍保留在历史记录中，漂移检查也仍然记录着这些端点。

选择工具集

JSM Operations API 大约有 240 个操作。若全部注册，会向客户端提供一个难以准确选择的工具列表，因此工具被划分为具有明确名称的工具集，由你选择：

另有三个工具集随附，但没有任何配置文件会加载它们——请参阅 已验证和未验证的内容：

此外还有四个配置文件，它们是上述工具集的组合包：

"env": { "JSM_TOOLSETS": "responder" }     // or "alerts,oncall", or "all"

名称可以自由组合，--toolsets=a,b 和 --read-only 标志会覆盖环境变量。名称不在上表中的话，服务会在启动时停止，并显示有效名称和建议——拼写错误不应该悄无声息地让你获得的工具少于所请求的数量。

core 是一份固定的名称列表——也就是本服务在工具集出现之前所提供的功能——保留它是为了让需要精确使用这些工具的安装无需逐一列出 13 个工具。组合使用时，它仍然只包含那 14 个工具：core,schedules 表示 core 加上所有排班工具，而不是两个系列都不受限制；因此，在它旁边添加工具集不会扩大 core 本身提供的范围。responder 则由其工具集派生，随着各系列陆续推出而扩展，这也是它成为默认配置的原因：一个警报服务如果大部分警报工具都不可见，除非重新配置，否则就没什么用。

all 表示每个已验证的工具集，而非每个工具集。 三个隔离的系列必须单独指定——JSM_TOOLSETS=all,heartbeats——这样选择全部工具时，就不会包含从未确认可正常工作的工具。

无论选择什么，都会始终注册 jsm_list_capabilities。 它会报告每个工具集、工具集是否已加载、所需权限范围以及用于更改配置的变量——因此，当你请求的功能不在当前选择范围内时，你会得到“该功能属于 oncall 工具集”，而不是“此服务无法执行该操作”。更改 JSM_TOOLSETS 需要重启；无法在对话过程中启用工具集。

所需权限范围。 警报和待命功能需要不同的权限范围，这是最常见的配置错误：

创建令牌前，值得了解以下三点：

• 写入也需要读取权限范围。 仅携带 write:ops-alert:jira-service-management 的令牌会失败。Atlassian 要求每个写入端点也同时具有读取权限范围。

• ops-config 是单独授予的权限，缺少它会返回 401，而非 403。 如果不授予此权限，9 个警报工具会正常工作，而 4 个待命工具会失败——这看起来像凭据出了问题，但实际上并非如此。两种配置都受支持：只授予读取权限范围，或者只授予 ops-alert，都是有意缩小 Agent 可访问范围的方式。

• Jira 用户权限范围是可选的，缺少时会明确提示，而非悄无声息。 Operations API 返回的每位响应人员都是一个纯账号 ID（712020:9ae5385e-…）；拥有 read:jira-user 时，待命工具会在同一次调用中将这些 ID 转换为姓名和电子邮件地址。没有该权限时，工具仍会响应——你会得到 ID，另附一行说明需要哪个权限范围才能获取姓名。知道谁在待命比知道他们的显示名称更重要，因此缺少此权限不会导致错误。

  请使用 read:jira-user，而不是 read:user:jira。细粒度权限方案确实覆盖这些端点，但必须包含完整的一组权限：read:application-role:jira + read:group:jira + read:user:jira + read:avatar:jira——单独使用 read:user:jira 并不足够，而且 Atlassian 仍将这组细粒度权限标记为此 API 的 Beta 功能。 团队可见性。 该账号还需要拥有相关团队的 JSM Operations 访问权限。告警和排班都属于团队的 Operations 页面，因此无法查看该团队的凭据会得到空列表，而不是错误。

示例

询问当前谁在值班时，会调用 jsm_list_schedules，然后调用 jsm_get_on_call：

你 — 现在谁在 payments 值班？

# Currently on-call for Payments — Primary

- Dana Okafor

确认告警会返回一份回执，而不是更新后的告警——因为 JSM 会在带外处理告警操作：

你 — 确认告警 4f2a9c1e-…-1718395200000，我正在查看

Acknowledge request accepted for alert `4f2a9c1e-…-1718395200000`.

- **Request id**: `c7b41f30-…`
- **Result**: Request will be processed

JSM applies alert actions asynchronously, so the alert may not reflect this
change immediately. Confirm with jsm_get_request_status using the request id
above, or re-read the alert after a moment.

最后这段说明至关重要：没有它，Agent 会重新读取告警，发现它仍未确认，于是再次确认。

工具

十个工具集共包含 95 个工具：alerts、alert-actions、oncall、schedules、teams、maintenance、routing、heartbeats、attachments 和 forwarding。默认注册前三个；其余工具集只有在 JSM_TOOLSETS 指定时才会加载，jsm_list_capabilities 会在运行时报告此安装实际具备哪些工具集。

TOOLS.md 是工具目录：列出每个工具及其对应的端点、它是读取还是写入操作、哪些工具被标记为具有破坏性，以及每个工具系列附带的注意事项。

使用 JSM_TOOLSETS 或 JSM_READ_ONLY 缩小范围——请参阅选择工具集。

此服务为你处理的事项

有三种 API 行为会悄无声息地破坏简单的集成。每种行为都写在工具描述中，模型实际会读取这些描述：

1. 写入操作是异步的。 每个修改端点都会立即返回 { result, requestId, took }，并在带外应用更改。确认告警后立即重新读取，往往会发现它仍未确认。正确的验证方式是调用 jsm_get_request_status，每个写入工具都会指向它。

2. tinyId 不是 ID。 JSM 界面中的短编号（#4821）会被 /v1/alerts/{id} 拒绝，因为该端点只接受完整的 uuid-timestamp ID。别名需要使用完全不同的端点（/v1/alerts/alias?alias=）。架构描述和 404 处理程序都会明确说明这一点，因此模型会自行纠正，而不是重复发起相同调用。

3. 搜索窗口上限为 20,000。 offset + limit 必须小于该上限。jsm_list_alerts 会在本地拒绝超出范围的翻页请求，并提示模型缩小查询范围，避免为注定返回 400 错误的请求浪费一次往返。

4. 告警操作不接受操作者或备注。 Opsgenie 允许在确认或关闭告警时附带 user、source 和 note，而 JSM Operations 是迁移到 Atlassian 的 Opsgenie——但它为这些端点声明了请求体，且会静默丢弃这些字段。确认时添加备注并读取活动日志，结果既看不到备注，也看不到操作者。因此，这些工具根本不提供这些参数：被拒绝的参数是模型可以据此采取行动的事实，而被忽略的参数看起来像是已记录的决定，实际却已消失。要留下持久备注，请调用 jsm_add_alert_note。jsm_create_alert 确实接受 note 和 source，因为 CreateAlertRequest 声明了这两个字段，且 API 会遵循这些参数——这一点也已验证。

此项目的存在意义

告警不是工作项。 它们位于另一个 API — /jsm/ops/api，即重新托管的 Opsgenie 接口 — 后面，拥有自己的作用域、自己的 ID 格式，以及自己的异步写入语义。MCP Registry 列出了 30 个 Jira 服务；它们全都面向工作项。没有一个能告诉你此刻是什么在触发寻呼。 atlassian/atlassian-mcp-server 缩小了差距，但并未弥合差距。自 2026 年 2 月起，它提供了四个 JSM Operations 工具 — getJsmOpsAlerts、getJsmOpsScheduleInfo、getJsmOpsTeamInfo 和 updateJsmOpsAlert — 但它们功能粗略：单个 updateJsmOpsAlert 涵盖确认、取消确认、关闭和升级，而备注、日志、标签、附件、暂停、分配、请求状态、时间线、轮换、覆盖、心跳、维护、路由、集成或审计日志都没有对应工具。它们也未出现在该仓库的 README 中，仅记录在 Atlassian 的支持的工具页面上，而且发布时仅支持 API 令牌 — 使用 OAuth 安装的用户看不到这些工具。作为托管的闭源服务，这些缺口只能由 Atlassian 弥补，而非通过贡献来修复。

现有的 Opsgenie MCP 服务使用的是即将停用的 API。 giantswarm/mcp-opsgenie、burakdirin/opsgenie-mcp-server 和 daviddykeuk/opsgenie-mcp 都使用 GenieKey 调用 api.opsgenie.com。Opsgenie 已于 2025 年 6 月 4 日停止销售，并将于 2027 年 4 月 5 日关闭，届时这些 REST API 将停止响应。本服务面向取代它们的接口：https://api.atlassian.com/jsm/ops/api/{cloudId}/v1。

兼容性。 适用于使用 JSM Operations 的 Atlassian Cloud 租户 — 已从独立 Opsgenie 迁移的网站，或合并后开通的网站。如果你的团队仍通过 app.opsgenie.com 登录并使用 GenieKey 进行身份验证，本服务将无法访问你的数据；上面的某个 Opsgenie 服务可以，直到 2027 年为止。

项目布局

src/
├── index.ts                 # transports and startup credential validation
├── server.ts                # assembles the catalogue from the eight families
├── toolsets.ts              # toolsets, profiles, and selection resolution
├── constants.ts             # API root, limits
├── types.ts                 # JSM API interfaces
├── schemas/common.ts        # Zod fragments shared across families
├── services/
│   ├── client.ts            # auth, request, envelope normalisation, error mapping
│   ├── directory.ts         # resolves bare Atlassian ids to names
│   ├── name-cache.ts        # one registry for every process-wide cache
│   ├── format.ts            # markdown rendering, truncation, result envelopes
│   └── render/              # per-family renderers
└── tools/
    ├── define.ts            # defineTool() + registerTools()
    ├── family.ts            # the resource-family factory
    ├── execute-write.ts     # the shared write executor
    ├── list-executor.ts     # the shared list pipeline
    ├── paging.ts            # the paging dialects each endpoint wants
    ├── capabilities.ts      # jsm_list_capabilities
    ├── test-support.ts      # stub client and in-memory MCP harness
    ├── alerts/              # alert reads
    ├── actions/             # alert writes
    ├── oncall/              # who is on call now and next
    ├── schedules/           # schedules, rotations, overrides
    ├── teams/               # teams, roles, contact methods
    ├── maintenance/         # maintenance windows
    ├── heartbeats/          # heartbeat monitors
    └── routing/             # escalations, routing, notification, forwarding rules

告警系列的工具按每个文件一个工具编写：一个模块负责自己的输入结构、描述和处理函数，不涉及其他内容。配置系列则由程序生成 — family.ts 根据 ResourceConfig 构建机械化的列表／获取／创建／更新／删除结构，因为手动编写这十种结构会产生上百个文件，而它们之间的差异每个只有三行。对于不符合这五种结构的端点，则在生成的工具旁边放置手写工具；teams/contacts.ts 同时包含两者。

server.ts 将八个系列合并为完整目录 allTools。toolsets.ts 将其缩减为进程实际注册的工具，而 index.ts 只处理传输方式。工具目录本身 — 按系列分组的所有工具 — 收录在 TOOLS.md 中。

这里有三项约定至关重要，意外更改它们是导致服务出现微妙故障的最可能原因。它们以及各自缘由，都记录在值得保留的约定中。

贡献

开发流程、值得保留的约定以及如何添加工具，请参阅 CONTRIBUTING.md。问题和 PR 中不得包含云 ID、令牌或真实告警数据。

安全

本服务持有 Atlassian 凭据，而 HTTP 传输本身不执行身份验证 — 威胁模型、加固说明以及如何私下报告漏洞，请参阅 SECURITY.md。

许可证

Apache-2.0