jira-mcp

一个基于 Model Context Protocol 的 Jira Cloud 服务器。可以创建问题和子任务、读取问题、使用 JQL 搜索、查看敏捷看板及其泳道、把问题沿工作流流转、添加评论以及附加文件。

它使用 Atlassian 账户邮箱和 Task API 令牌进行认证，因此可以无头运行——没有 OAuth，没有浏览器往返，也没有交互式授权。

安装

无需安装。将你的 MCP 客户端指向该包，让 npx 去获取它：

{
  "mcpServers": {
    "jira": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:skurekjakub/jira-mcp#v1.0.0"],
      "env": {
        "NPM_CONFIG_ALLOW_GIT": "root",
        "JIRA_SITE": "your-team.atlassian.net",
        "JIRA_CLOUD_ID": "00000000-0000-0000-0000-000000000000",
        "JIRA_PROJECT_KEY": "ABC",
        "JIRA_EMAIL": "${JIRA_EMAIL}",
        "JIRA_API_TOKEN": "${JIRA_API_TOKEN}"
      }
    }
  }
}

构建产物已提交，运行时依赖也已内联其中，所以当前是克隆和链接安装——没有构建步骤，不拉取任何包，也不需要批准专门脚本。

NPM_CONFIG_ALLOW_GIT

npm 12 默认将 allow-git 设为 none，所以若不设置，npm 会以 EALLOWGIT 拒绝安装——"Fetching packages of type git have been disabled"。在服务器的 env 块中设置它，可以把豁免范围限定为这一个子进程，而不会影响机器上其他安装的 git 获取。root 允许所要安装的包使用 git，但不允许其任何依赖使用；all 会完全取消限制，而这里用不到。在 npm 11 及更早版本中，这个变量会被忽略。

改为一次性安装

npx 每次启动都会重新解析 git 引用，这需要十几秒和一次网络往返。要避免这两者，可以：

npm install -g --allow-git=root github:skurekjakub/jira-mcp

然后使用 "command": "jira-mcp"，不带 args，也不带 NPM_CONFIG_ALLOW_GIT。之后升级就是手动重新运行这条命令。

Related MCP server: JIRA MCP Server

配置

所有设置都来自环境变量。没有配置文件，服务器也不读取 .env —— MCP 客户端在上面的 env 块中传入这些变量。

可用以下方式找到站点 ID：

curl -s https://your-team.atlassian.net/_edge/tenant_info

将令牌排除在版本控制之外

已提交线到版本库的 MCP 配置不能包含令牌本身。Claude Code 在 command、args、env、url、n headers 中扩展 ${VAR} 引用，因此让配置只写一个变量名，而把这些值存在其他地方——一个 shell 配置文件或一个不提交 settings 文件。

没有任何东西扩展的引用 不是 错误：Claude Code 会把文字量 ${JIRA_API_TOKEN} 直接传给服务器。本服务器在启动时就会拒绝这种形态的值，列出具体变量名，而不会把它发给 Jira 后返回一个含义不明的 401。

工具

jira_create_issue

在 JIRA_PROJECT_KEY 中创建一个问题。问题。

| Parameter | Type | 必填 | 描述 | | ------------------------- | --------- | ----- | ----- | ------ | | summary | string | yes | 问题标题 | | description | string | yes | 纯文本，转换为 ADF（按空行分款）； | | issueType | string | no | 例如 Task、Bug、Story（默认 Story） | | labels | string[] | no | 可选标签 | | parentKey | string | no | 放在父级下层的链接，例如 Epic——只有项目的 issue-type 类型层级允许时才有效 |

jira_create_subtask

创建一条内置子任务位于现有问题的子任务。

jira_get_issue

获取问题摘要、描述、类型、状态、父问题、子任务、问题链接和修复版本。

jira_search_issues

使用 JQL 搜索，分页返回。

jira_get_board

报告敏捷看板的布局：列、快捷筛选器和泳道，以及它们各自的 JQL。在运行 jira_board_issues 前调用它，可以知道该工具接受的名字。看板 ID 是看板 URL 中 boards/<id> 这一段。

泳道来自 GreenHopper 提供的内部 API，Atlassian 并没有提供公共支持的端点。

jira_board_issues

列出当前看板上已有的问题，按泳道分组。它完整再现了看板视图：看板自己的筛选条件、kanban 子筛选、罗列的快捷筛选器和额外的 JQL。

每个问题只会进入多正好一个泳道——看板顺序中第一个、其查询能匹配到它的泳道。就算你只要一个真. 部分泳道，系统仍会计算这些泳道上层的泳道，所以这些泳道对问题所属、仍然覆盖。

jira_list_transitions

列出该问题当前可用的工作流转发。转换名称和 ID 是跟随工作流程配置的——先调用它再调用 jira_transition_issue。

jira_transition_issue

把问题沿其工作流转换。transitionName 会大小不区别地匹配该问题可用转换；如果没有匹配，则返回有效的转换列表并失败。

jira_add_comment

添加评论。正文使用 Jira wiki markup（h3. 一段标题、{{code}} 嵌入行内代码、{code:lang}…{code} 表示代码块、bq. 表示引用）。请用真的换行，而不是输入凭面的 \n 转义。

jira_add_attachment

添加一个文件。该文件必须位于 JIRA_ATTACHMENTS_DIR内；任何转到目录之外的文件名都会被已有的拒绝。

传输

默认通过配置启用 stdio。使用 --transport http --port <n> 启动后，同样的工具可通过 /mcp 的 Stateless Streamable HTTP 传输提供，并在 /health 上进行健康检查。

开发

npm install
npm test          # vitest
npm run lint      # tsc --noEmit
npm run build     # webpack -> dist/bundle.js

提交 dist/bundle.js，因此安装无需再进行编译。CI 会在每次向 main 分支推送时重建它并提交结果，所以它不会 drift 出 src/。

License

MIT