Skip to main content
Glama

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
  1. 在 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 令牌

使用

配置完成后,你可以通过 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 文档格式 JSON

.txt, .text

plain

纯文本,包裹在段落中

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

{
  "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 凭据

  • 缺少活跃的冲刺

  • 无效的项目键或问题键

  • 网络错误

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Provides tools for AI assistants to interact with JIRA APIs, enabling them to read, create, update, and manage JIRA issues through standardized MCP tools.
      6
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables natural language interaction with JIRA through MCP, providing 35 tools for issues, comments, transitions, projects, boards, sprints, epics, links, worklogs, versions, attachments, users, and fields.
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables natural language interaction with Jira Cloud tickets, including listing, searching, creating, and updating issues through a set of MCP tools.
      -