JIRA MCP Server

JIRA MCP 服务

这是一个用于与 JIRA 交互的模型上下文协议（MCP）服务。你可以通过 MCP 接口获取活跃冲刺中的工单，并查看工单的详细信息。

功能

该服务提供以下工具：

1. list-sprint-tickets：获取指定项目活跃冲刺中的所有工单

   • 必需参数：projectKey（字符串）

2. get-ticket-details：获取特定工单的详细信息

   • 必需参数：issueKey（字符串）

3. add-comment：为特定工单添加评论

   • 必需参数：issueKey（字符串）
   • 需提供 comment（字符串）或 filePath（字符串）——请参阅从文件编辑内容
   • 可选参数：commentFormat——plain（默认）、wiki、markdown 或 adf

4. link-issues：将每个外向工单与每个内向工单关联，含义为“外向工单 阻塞 内向工单”

   • 必需参数：outwardIssueKeys、inwardIssueKeys（字符串数组）——使用 linkType: "Blocks" 时，外向工单是阻塞方
   • 可选参数：linkType——关联类型名称（Blocks，或在类型带编号的站点上使用 3. Blocks），也可以是其内向／外向描述；默认为 Relates。unlink-issues 接受相同的值。
   • 结果以文字形式报告，例如 PROJ-1 blocks PROJ-2

5. update-description：更新特定工单的描述

   • 必需参数：issueKey（字符串）
   • 需提供 description（字符串）或 filePath（字符串）——请参阅从文件编辑内容
   • 可选参数：descriptionFormat——plain（默认）、wiki、markdown 或 adf

6. list-child-issues：获取父工单的所有子工单

   • 必需参数：parentKey（字符串）

7. create-sub-ticket：为父工单创建子工单（子问题）

   • 必需参数：parentKey（字符串）
   • 必需参数：summary（字符串）
   • 可选参数：description（字符串）或 filePath（字符串）——请参阅从文件编辑内容
   • 可选参数：issueType（字符串）- 子任务问题类型的名称（例如，'Sub-task'）

8. add-attachment：将本地文件上传为工单附件

   • 必需参数：issueKey（字符串）
   • 必需参数：filePaths（字符串数组）——上传前会检查所有路径；如果有无效路径，则不会上传任何文件

9. notifications：读取你的 Atlassian 通知（铃铛图标），按时间从新到旧排列

   • 可选参数：since / until——ISO 日期／时间（2026-10-01、2026-10-01T09:00:00Z）或从当前时间往前计算的时长（30m、24h、7d、2w）
   • 可选参数：limit（数字）——默认为 20，最大为 100
   • 可选参数：unreadOnly（布尔值）、category（direct 或 watching）、product（例如，jira、confluence）
   • 可选参数：ids（字符串数组）——仅返回这些通知（每条结果中的 ID: 行）；忽略其他筛选条件和 limit
   • 可选参数：markAsRead（布尔值，默认为 false）——将返回的未读通知标记为已读，因此使用 ids + markAsRead 可准确标记指定通知；分组通知会作为整体标记。API 无法删除或忽略通知。
   • 通知来自 Atlassian GraphQL 网关（/gateway/api/graphql），该网关接受相同的 API 令牌。系统会请求 JIRA_HOST 中站点的通知流（通过公开的 /_edge/tenant_info 读取其 cloud ID）；如果不进行此路由，网关只会返回平台范围的管理员通知。

设置

1. 安装依赖：

   npm install
   

2. 构建 TypeScript 代码：

此步骤仅适用于 Windows 上的 Cline，因为目前 Cline 存在无法执行 npx 的问题。

npm run build

3. 在 Claude 应用设置文件中配置 MCP 设置（在 macOS 上通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json，在 Windows 上通常位于 %APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json）：

Claude 的设置：

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["path/to/this/repo/jira.ts"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Cline 的设置：

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["path/to/this/repo/dist/jira.js"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

配置

你需要在 MCP 设置中配置以下环境变量：

1. JIRA_HOST：你的 Atlassian 域名 URL（例如，https://your-company.atlassian.net）
2. JIRA_EMAIL：你的 JIRA 账户邮箱
3. JIRA_API_TOKEN：你的 JIRA API 令牌
   • 你可以在 Atlassian 账户设置中生成 API 令牌

用法

配置完成后，你可以通过 Claude 中的 MCP 接口使用这些工具：

列出冲刺工单

获取某个项目当前冲刺中的所有工单：

<use_mcp_tool>
<server_name>jira</server_name>
<tool_name>list-sprint-tickets</tool_name>
<arguments>
{
  "projectKey": "YOUR_PROJECT_KEY"
}
</arguments>
</use_mcp_tool>

获取工单详情

获取特定工单的详细信息：

<use_mcp_tool>
<server_name>jira</server_name>
<tool_name>get-ticket-details</tool_name>
<arguments>
{
  "issueKey": "PROJECT-123"
}
</arguments>
</use_mcp_tool>

编辑文件中的内容

update-description、update-comment、add-comment、create-ticket 和 create-sub-ticket 支持使用 filePath 代替内联文本。此功能适用于较长的内容：将源内容保存在 文件中，编辑该文件，然后重新发送——无需每次都通过工具调用重新提交整个正文。在两个创建工具中，描述仍为可选项，因此两者都省略也没问题。

格式会根据扩展名自动推断，因此可以省略 descriptionFormat / commentFormat：

扩展名	格式	内容
.md、.markdown	markdown	Markdown（## headings、**bold**）
.wiki、.jira	wiki	Jira wiki 标记（h2.、{code}）
.json、.adf	adf	原始 Atlassian Document Format JSON
.txt、.text	plain	纯文本，会包装在一个段落中

显式传入格式会覆盖扩展名，这也是使用其他扩展名文件的方式。路径可以是绝对路径，也可以是相对于服务工作目录的路径。

{
  "issueKey": "PROJECT-123",
  "filePath": "/abs/path/to/description.md"
}

空文件会被拒绝，而不会清除现有描述或评论；同时传入内联文本和 filePath 则会报错。

对于最终内容为空的 Markdown 结构——表格单元格（表头或正文）、列表项、引用块、围栏代码块——系统会在发送前将其修复为有效的 ADF。Jira 验证器会拒绝空的 tableHeader / tableCell / listItem / blockquote，并返回只指出字段（errors.comment）而非出错节点的 400 INVALID_INPUT。因此，如果没有此修复，整条评论看起来都会被拒绝，实际上问题只出在一个空单元格。

修改现有内容

若要更改现有描述或评论的部分内容，请先使用 export-content 导出，再编辑文件并重新上传——无需重写全部内容：

{ "issueKey": "PROJECT-123", "commentId": "54660", "filePath": "/tmp/pir-timeline.md" }

导出结果会说明该内容是否适合安全地重新上传为 markdown。Jira 会将内容存储为 ADF，而面板、提及、状态标签、媒体、表格、任务列表和展开块等结构都没有对应的 markdown 格式——重新上传 markdown 会悄无声息地丢失这些内容。存在此类结构时，工具会发出警告并列出它们；请改用 "format": "adf" 导出并修改 JSON，这样始终可以精确地往返转换（上传时，.json 文件会被识别为 ADF）。

省略 filePath 可直接以内联形式返回内容，而不是写入文件。评论 ID 可通过 get-ticket-details 查看。

内容版本（乐观并发控制）

当要替换的内容不为空时，update-description 和 update-comment 都需要 expectedVersion：也就是编辑所基于的版本。如果 Jira 中的内容在此期间发生变化，更新就会被拒绝，而不是悄悄丢弃该更改——这与 Confluence 通过页面版本号实现的锁定机制相同。

Jira 本身没有版本号，而问题的 updated 时间戳不能替代版本号：任何问题变更都会更新该时间戳，因此状态流转、标签和新评论都会导致描述补丁被拒绝，即使这些变更与补丁毫无冲突。因此，版本号是根据内容本身计算的哈希值（v1-…），只有要修补的内容发生变化时才会改变。

版本号来自 export-content 和 get-ticket-details。后者会报告 Description version:，并为每条评论报告一个 version:，因此小范围的行内编辑无需往返导出。

首次编写描述时不需要版本号。 省略 expectedVersion 本身就是在声明“这里还没有内容”，服务端会对此进行检查：如果描述仍为空，就会写入；如果期间有人写入了描述，写入就会被拒绝，并告知 Jira 中当前的版本号。因此，即使是首次写入也受锁定保护，调用方无需获取空内容的版本号。

传入 "force": true 可跳过检查并强制覆盖。

在描述和评论中嵌入文件

add-comment、update-comment、update-description、create-ticket 和 create-sub-ticket 会嵌入使用内容格式中的图片语法引用的文件：

![the error dialog](./screenshots/error.png)

!error.png!          (wiki, image)
[^report.pdf]        (wiki, file)

每个引用都会解析为问题附件。Jira 会将评论中显示的文件存储为问题附件，因此评论和描述的处理方式相同。引用按以下顺序解析：

1. attachment:<filename or ID> 会嵌入工单上已有的附件。
2. 本地路径（相对于内容文件，或对于行内文本则相对于服务的工作目录）会被上传。如果工单上已有同名同大小的附件，则会复用该附件，因此重新发送编辑过的文件不会再次附加同一张截图。
3. 否则，会使用工单上已有的同名附件。

在上传或写入任何内容之前，都会检查所有引用。只要有一个引用无效，调用就会失败，且不会更改任何内容。Web URL（https://…）会保持原样。图片会以内嵌方式显示，其他文件则显示为附件链接。创建工单时，描述会在问题创建后通过第二步写入，因为只有已存在的问题才能添加附件。

开发

该服务使用 TypeScript 编写，并使用：

• @modelcontextprotocol/sdk 实现 MCP 服务
• jira.js 集成 JIRA API

推荐的脚本：

• 构建一次：npm run build
• 构建并监听：npm run build:watch
• 仅进行类型检查：npm run typecheck
• 以开发模式运行并监听：npm run start:dev
• 运行编译后的服务：npm start
• 检查格式：npm run fmt:check
• 写入格式化结果：npm run fmt
• 单元测试：npm test

npm test 只运行单元测试。测试使用模拟的 Jira 客户端，无需凭据，也不会接触真实的 Jira 实例。针对实时 Jira 的检查若会创建工单、评论或附件，则会手动作为一次性脚本运行，且不会提交到代码库。任何一种测试都不应提交真实 Jira 实例的详细信息，例如主机名、项目键、问题键、人员姓名或附件 ID。

典型工作流：

1. 修改 jira.ts
2. 开发期间运行 npm run start:dev；或者运行 npm run build，然后运行 npm start 以启动编译后的服务
3. 如有需要，重启 MCP 客户端以应用更改

错误处理

该服务包含以下错误的处理逻辑：

• JIRA 凭据无效
• 没有活动冲刺
• 项目键或问题键无效
• 网络错误

错误消息会在工具响应中返回。