jira-alerts-mcp

一个面向 Jira Service Management Operations REST API 的 MCP 服务器——用于告警与值班（on-call）。

为什么存在

**告警不是工作项。**它们位于另一套 API 之后——/jsm/ops/api，即重新托管后的 Opsgenie 界面——拥有自己的作用域、自己的 id 格式，以及自己的异步写入语义。MCP Registry 列出了 30 个 Jira 服务器；它们全部只针对工作项。没有哪一个能告诉你此刻是什么正在寻呼你。

官方的 Atlassian MCP 服务器并没有填补这一空白。atlassian/atlassian-mcp-server 覆盖了 Jira、Confluence、Jira Service Management 请求、Bitbucket、Compass 和 Teamwork Graph。它没有任何用于告警、排班或值班的工具。它同时也是一个托管式的封闭服务器——该仓库只存放 manifests 和 skills，而不存放 handlers——因此这个空白只能由 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 将停止响应。相关功能已迁移到 Jira Service Management 中。

本服务器面向的正是取代它们的 API 表面：使用 OAuth 或 Atlassian API token 访问 api.atlassian.com/jsm/ops/api/{cloudId}。你可以搜索告警、读取告警的备注与活动时间线、确认 / 关闭 / 添加备注 / 添加响应人，并查询当前和下一个值班的人是谁。

Related MCP server: Jira & Confluence MCP Server

兼容性

适用于拥有 JSM Operations 的 Atlassian Cloud 租户——也就是已从独立 Opsgenie 迁移出来的站点，或是在合并之后新开通的站点。如果你的团队仍然登录 app.opsgenie.com 并使用 GenieKey 认证，本服务器将无法访问你的数据；上面提到的某个 Opsgenie 服务器可以，但只能用到 2027 年。

基础 URL：https://api.atlassian.com/jsm/ops/api/{cloudId}/v1

工具

刻意不实现：DELETE /v1/alerts/{id} 和告警创建。删除告警会销毁审计历史且无法撤销；而告警创建属于集成 API（/jsm/ops/integration/v2/alerts）的职责范围——它需要 integration key，而不是交互式代理该做的事。如果你有具体需求，请提交 issue。

工具描述中写明的三个 API 行为

这些是会悄无声息地破坏天真集成的细节，因此它们被明确写进了工具描述里，模型实际会读到这些内容：

1. **写入是异步的。**每个变更端点都会立即返回 { result, requestId, took }，并在带外应用更改。刚执行确认（ack）后立刻重新读取告警，往往仍会显示为未确认。jsm_get_request_status 是正确的验证路径，每个写入工具都会指向它。

2. **tinyId 不是 id。**JSM UI 中的短编号（#4821）会被 /v1/alerts/{id} 拒绝——该端点只接受完整的 uuid-timestamp 格式 id。别名则需要一个完全不同的端点（/v1/alerts/alias?alias=）。schema 描述和 404 处理器都明确说明了这一点，因此模型会自我纠正，而不是重试同一个调用。

3. 搜索窗口上限为 20,000。offset + limit 必须保持在该值以下。jsm_list_alerts 会在本地拒绝更深的翻页，并提示模型收窄查询范围，而不是在注定返回 400 的调用上浪费一次往返。

设置

需要 Node ≥ 22。

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

配置

复制 .env.example 作为参考。请注意，服务器不会自己读取 .env——MCP 服务器由其客户端启动，环境由客户端掌管。请将该文件作为客户端 env 块的核对清单；本地开发时也可以使用 set -a; source .env; set +a。

凭据会在启动时进行校验，因此错误的配置会立即失败并给出可操作的提示，而不是在第一次工具调用时才报错。

**查找你的 cloud id。**在登录状态下打开 https://<your-site>.atlassian.net/_edgeAuth/tenantInfo，或者使用你的 token 调用 GET https://api.atlassian.com/oauth/token/accessible-resources。

**所需作用域。**读取工具需要 read:ops-alert:jira-service-management；写入工具需要 write:ops-alert:jira-service-management。仅授予读取作用域是受支持的配置——此时写入工具会以 403 失败，并指出缺失的作用域。

该账号还需要具备相关团队的 JSM Operations 访问权限。告警和排班都挂在团队的 Operations 页面上，因此无法看到该团队的凭据会得到空列表，而不是报错。

接入 Claude Code

claude mcp add jsm-alerts \
  --env JSM_CLOUD_ID='your-cloud-id' \
  --env JSM_EMAIL='you@example.com' \
  --env JSM_API_TOKEN="${JSM_API_TOKEN}" \
  -- node /absolute/path/to/jira-alerts-mcp/dist/index.js

有两个容易踩坑的地方：服务器名称是第一个位置参数，位于任何标志之前；另外在 zsh 中 ${VAR} 需要加引号。对于通过 GUI 启动的会话，token 必须放在 ~/.claude/settings.json 的 env 块中——shell 环境不会被继承。

测试

npm test           # offline test suite — no network, no tenant
npm run inspect    # MCP Inspector against dist/index.js — needs credentials

进行真实环境检查时，先从 jsm_list_schedules 开始。它不需要任何 id，一次调用就能确认认证、作用域和团队可见性。

端点验证状态

这些路径都对照着 JSM ops REST API 参考文档 逐一核实过，而不是凭空假设：

• 已在官方文档中确认：/v1/alerts、/v1/alerts/{id}、/v1/alerts/alias、/v1/alerts/requests/{id}、/v1/alerts/{id}/acknowledge、/v1/alerts/{id}/close、/v1/alerts/{id}/responders、/v1/alerts/{id}/notes、/v1/schedules/{id}/on-calls、/v1/schedules/{id}/next-on-calls。

• 与 Opsgenie 保持一致，值得在首次运行时确认：GET /v1/alerts/{id}/logs 以及备注/日志翻页的确切查询参数（order、offset 游标）。JSM Operations 是 Opsgenie API 的重新托管版，这些内容在那里没有变化；但文档站点采用客户端渲染，无法端到端地完整读取。

• 集合封装（collection envelope）：Atlassian 在集合是返回在 data 下还是 values 下这一点上并不一致。JsmClient.getCollection 两者都接受并会进行归一化，因此无论哪种情况都无需改动——但如果某个列表工具在你确信数据存在时返回零条记录，那么这个归一化器就是首先要检查的地方。

架构

src/
├── index.ts                 # transports and startup credential validation
├── server.ts                # assembles the tool domains
├── constants.ts             # API root, limits
├── types.ts                 # JSM API interfaces
├── schemas/common.ts        # Zod fragments shared across domains
├── services/
│   ├── client.ts            # auth, request, envelope normalisation, error mapping
│   └── format.ts            # markdown rendering, truncation, result envelopes
└── tools/
    ├── define.ts            # defineTool() + registerTools()
    ├── list-executor.ts     # the shared list pipeline
    ├── alerts/              # read tools — one file per tool, plus shapes.ts
    ├── actions/             # write tools, all via execute-action.ts
    └── oncall/              # schedules and on-call

每个文件对应一个工具。一个工具模块只拥有自己的输入结构（input shape）、描述和处理器，仅此而已——最大的也只有约 100 行。server.ts 负责拼接三个域导出的数组；index.ts 只关心传输层。

在你扩展它时，有三条约定值得保留：

• 每个列表工具都经由 executeList（tools/list-executor.ts）。它负责数据获取、空结果分支、截断至 25,000 字符、分页块以及格式切换。这段逻辑曾经分散在每个工具各自的副本中，也因此出现过两个 bug——空页面返回了被 SDK 拒绝的结果，以及 next_offset 跳过了因截断而被丢弃的记录。现在只有一份，这是有意为之。

• 每个写入操作都经由 executeAction（tools/actions/execute-action.ts），因此异步回执（async-receipt）约定不会在四个写入工具之间产生偏差。

• 分页报告的是实际交付的内容，而不是获取到的内容。count 和 next_offset 描述的是响应中实际存在的记录；当 API 返回的数据超出了可容纳范围时，truncated 会做出标记。

关于 inputSchema 的说明

MCP TypeScript SDK 的 registerTool 期望的是原始的 Zod shape（一个由 Zod 类型组成的普通对象），而不是 z.object(...)。正如一些示例所展示的，传入 z.object 会失败。这里的工具定义的是普通 shape，并通过 z.infer<z.ZodObject<typeof shape>> 推导其输入类型。由此带来的一个后果：.strict() 无法应用于原始 shape，因此未知键会被剥离而不是被拒绝。

与此相关，ToolResult 是类型别名（type alias），而不是接口（interface）：SDK 的 CallToolResult 带有索引签名（index signature），而 TypeScript 只会隐式地将索引签名授予类型别名。

贡献

开发循环、值得保留的约定以及如何新增工具，请参阅 CONTRIBUTING.md。Issue 和 PR 中不得包含 cloud id、token 或真实的告警数据。

安全

本服务器持有 Atlassian 凭据，且 HTTP 传输层本身不执行任何认证——威胁模型、加固建议以及如何私下报告漏洞，请参阅 SECURITY.md。

许可证

Apache-2.0