JIRA MCP Server

这是一个 Model Context Protocol (MCP) 服务器，提供与 JIRA 交互的工具。它允许你从活跃的冲刺中获取工单，并通过 MCP 接口获取详细的工单信息。

功能

该服务器提供以下工具：

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

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

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

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

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

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

   • 提供 comment（字符串）或 filePath（字符串）之一 — 参见 从文件编辑内容

   • 可选参数：commentFormat — plain（默认）、wiki、markdown 或 adf

4. link-tickets：以“关联”关系链接两个工单

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

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

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”）

Related MCP server: mcp-jira

设置

1. 安装依赖：

   npm install

2. 构建 TypeScript 代码：

此步骤仅适用于 Windows 上的 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": "your-email@example.com",
        "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": "your-email@example.com",
        "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：

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

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

空文件会被拒绝，而不是清除现有的描述或评论，同时传递内联文本和 filePath 是错误的。

修补现有内容

要更改已存在的描述或评论的一部分，请先使用 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 以跳过检查并无论如何覆盖。

开发

该服务器使用 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

典型工作流程：

1. 修改 jira.ts

2. 在开发期间运行 npm run start:dev，或先运行 npm run build 再运行 npm start 以进行编译运行

3. 如有需要，重启你的 MCP 客户端以获取更改

错误处理

该服务器包含以下错误处理：

• 无效的 JIRA 凭据

• 缺少活跃的冲刺

• 无效的项目键或问题键

• 网络错误

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