AI导哈

Jira MCP服务器

一个生产就绪的模型上下文协议（MCP）服务器，与Jira Cloud集成，并为GitHub Copilot Chat、Claude、Cursor、Kiro、JetBrains AI Assistant等MCP兼容客户端提供工具支持。

  • by Suvraneel
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 Suvraneel/JiraMCP

使用说明

Jira MCP服务器

生产准备就绪 模型上下文协议（MCP） 与集成的服务器 吉拉云 并公开了可供使用的工具 GitHub Copilot 聊天助手, 克劳德, 光标, 基罗, JetBrains AI 助手，以及其他MCP兼容客户端。

特征

工具 说明
get_jira_issue 按关键字获取单个问题（例如。 PROJ-123)
search_jira_issues 使用JQL搜索问题
add_jira_comment 添加新评论，或通过可选功能编辑现有评论 commentId
get_jira_comments 获取某个问题的所有评论
create_jira_issue 创建新问题（故事、任务、Bug、史诗、子任务）
search_jira_users 按姓名/电子邮件搜索用户以获取帐户ID
assign_jira_issue 按帐户ID将问题分配给用户
get_jira_transitions 列出问题的可用工作流转换
transition_jira_issue 将问题移动到目标工作流状态
update_jira_issue 更新问题摘要和/或描述
get_jira_issue_changelog 获取完整的问题字段更改历史记录
get_jira_link_types 列出可用的Jira问题链接类型
link_jira_issues 在两个问题之间创建链接（例如关联、块）
get_jira_boards 列出Jira板（Scrum/看板），可选项目过滤器
get_jira_sprint_issues 按sprint ID列出sprint中的问题

内置可靠性：

  • ✅ 具有60秒TTL的内存缓存（GET和搜索请求）
  • ✅ 自动重试，指数回退（最多3次尝试）
  • ✅ 费率限制处理——方面 Retry-After HTTP 429上的标头
  • ✅ 通过Zod模式进行输入验证
  • ✅ 结构化JSON响应（无原始Jira有效载荷）
  • ✅ 优雅的错误处理和有意义的消息

先决条件

要求 最低版本
Node.js ≥18升
npm ≥ 9
Git 任何最新版本
吉拉云 实例 REST API v3(/rest/api/3)

⚠️ Jira服务器/数据中心 可能有效，但尚未经过正式测试。此服务器的目标是Jira Cloud REST API v3。

1-生成Jira API令牌

  1. 登录您的Atlassian帐户
  2. 首选→ https://id.atlassian.com/manage-profile/security/api-tokens
  3. 点击 创建API令牌
  4. 给它贴上标签（例如。 “MCP服务器”)然后单击 创建
  5. 立即复制令牌 --你再也看不到了

💡 该令牌与您的Atlassian电子邮件绑定。你需要两者 电子邮件 和那个 令牌 用于身份验证。

2--克隆和安装

# Clone the repository
git clone https://github.com/<your-org>/JiraMCP.git
cd JiraMCP

# Install dependencies
npm install

已安装依赖项

包装 用途
@modelcontextprotocol/sdk MCP服务器框架
axios Jira REST API的HTTP客户端
dotenv 负载 .env config
zod 输入模式验证
typescript 构建工具链（开发）

3--配置环境变量

# Copy the example file
cp .env.example .env        # macOS / Linux
copy .env.example .env      # Windows (cmd)

编辑 .env 与你的价值观：

JIRA_BASE_URL=https://your-domain.atlassian.net
JIRA_EMAIL=your-email@example.com
JIRA_API_TOKEN=your-api-token-here
变量 描述 示例
JIRA_BASE_URL 您的Jira Cloud实例URL（无尾随斜线） https://mycompany.atlassian.net
JIRA_EMAIL 链接到您Atlassian帐户的电子邮件地址 dev@mycompany.com
JIRA_API_TOKEN 步骤1中生成的API令牌 ATATT3xFfGF0...

⚠️ 永不承诺 .env 版本控制。 它已在中列出 .gitignore.

4--构建和运行

# Compile TypeScript → dist/
npm run build

# Start the MCP server (stdio transport)
npm start

对于自动编译的开发：

npm run dev

运作原理

服务器使用 stdio传输 --它从以下位置读取JSON-RPC消息 stdin 并将回复写入 stdout。所有诊断/日志消息都转到 stderr 因此它们永远不会干扰MCP协议。

你 不要 直接在终端中与它交互。相反，您可以将IDE配置为将其作为子进程启动（见下文）。

5--客户端配置

详细的 mcp.json 说明分为每个客户端的指南（每个指南都包括Windows/macOS/Linux路径（如适用））：

  • GitHub Copilot（VS代码+JetBrains）： docs/mcp/github-copilot.md
  • 克劳德桌面： docs/mcp/claude.md
  • 克劳德代码（CLI）： docs/mcp/claude-code.md
  • 光标（桌面/UI）： docs/mcp/cursor.md
  • 光标CLI： docs/mcp/cursor-cli.md
  • Kiro（桌面/UI）： docs/mcp/kiro.md
  • Kiro命令行界面： docs/mcp/kiro-cli.md
  • 其他支持MCP的客户端（兼容性说明）： docs/mcp/other-clients.md

快速提醒所有客户：

  • 使用 node 作为命令。
  • 将参数指向的绝对路径 dist/server.js.
  • 提供 JIRA_BASE_URL, JIRA_EMAIL，以及 JIRA_API_TOKEN 在环境变量中。
  • 更改MCP配置后重新启动客户端。

6--验证其是否有效

配置后，在IDE中打开Copilot Chat并尝试：

提示 工具已调用
“获取DEV-5的详细信息” get_jira_issue
“在MYAPP项目中搜索打开的bug” search_jira_issues
“查找我过去2天的进度问题” search_jira_issues
“在DEV-5中添加注释，说明已部署修复程序” add_jira_comment
“编辑DEV-5上的评论10036，表示回滚已完成” add_jira_comment
“在DEV-5上显示评论” get_jira_comments
“列出DEV-5的转换” get_jira_transitions
“将DEV-5移动到进行中” transition_jira_issue
“将DEV-5摘要更新为‘重构身份验证模块’” update_jira_issue
“显示DEV-5的更新日志” get_jira_issue_changelog
“列出问题链接类型” get_jira_link_types
“链接DEV-5和DEV-8” link_jira_issues
“列出DEV项目中的板” get_jira_boards
“获取sprint 123的sprint问题” get_jira_sprint_issues

可选：运行实时端到端工具测试脚本

npm run build
node test-all-tools.mjs

此脚本针对您配置的Jira实例练习所有15个工具，并打印通过/失败摘要。

项目结构

JiraMCP/
├── docs/
│   └── mcp/
│       ├── github-copilot.md  # VS Code + JetBrains MCP config
│       ├── claude.md          # Claude Desktop MCP config
│       ├── claude-code.md     # Claude Code (CLI) MCP config
│       ├── cursor.md          # Cursor desktop MCP config
│       ├── cursor-cli.md      # Cursor CLI MCP config
│       ├── kiro.md            # Kiro desktop MCP config
│       ├── kiro-cli.md        # Kiro CLI MCP config
│       └── other-clients.md   # Compatibility notes for additional MCP clients
├── src/
│   ├── server.ts              # MCP server setup & tool registration
│   ├── jiraClient.ts          # Jira REST API v3 wrapper (cache, retry, rate-limit)
│   └── tools/
│       ├── getIssue.ts        # get_jira_issue tool
│       ├── searchIssues.ts    # search_jira_issues tool
│       ├── addComment.ts      # add_jira_comment (add/edit)
│       ├── getComments.ts     # get_jira_comments
│       ├── createIssue.ts     # create_jira_issue
│       ├── assignIssue.ts     # assign_jira_issue
│       ├── searchUsers.ts     # search_jira_users
│       ├── getTransitions.ts  # get_jira_transitions
│       ├── transitionIssue.ts # transition_jira_issue
│       ├── updateIssue.ts     # update_jira_issue
│       ├── getIssueChangelog.ts # get_jira_issue_changelog
│       ├── getLinkTypes.ts    # get_jira_link_types
│       ├── linkIssues.ts      # link_jira_issues
│       ├── getBoards.ts       # get_jira_boards
│       └── getSprintIssues.ts # get_jira_sprint_issues
├── dist/                      # Compiled JS output (generated by `npm run build`)
├── test-all-tools.mjs         # Live Jira integration test for all tools
├── package.json
├── tsconfig.json
├── .env.example               # Template for environment variables
├── .gitignore
├── AGENTS.md                  # AI agent instructions for tool usage
└── README.md                  # This file

故障排除

问题 原因 修复
Missing required environment variables .env 未找到或不完整 确保 .env 存在所有3个变量，或通过传递它们 env 在MCP配置中
Jira API error (HTTP 401) 凭据错误 仔细检查 JIRA_EMAIL 和 JIRA_API_TOKEN
Jira API error (HTTP 403) 权限不足 确保API令牌的帐户有权访问目标Jira项目
Jira API error (HTTP 404) 未找到问题 验证问题密钥是否存在（例如。 DEV-5，不 dev-5)
Jira API error (HTTP 410) 已弃用的API终结点 请确保您使用此服务器的最新版本（使用 /rest/api/3/search/jql)
Jira API error (HTTP 429) 速率受限 服务器自动重试；如果持续存在，请降低请求频率
ECONNREFUSED / ETIMEDOUT 网络问题 验证 JIRA_BASE_URL 可以联系到(curl https://your-domain.atlassian.net)
工具在副驾驶聊天中不可见 未加载MCP配置 重新启动IDE；验证 mcp.json 语法是有效的JSON
node 找不到 Node.js不在PATH中 安装Node.js或使用完整路径 node 在MCP配置中

平台特定注意事项

操作系统 Node.js安装 路径分隔符
视窗 nodejs.org 或 winget install OpenJS.NodeJS.LTS 使用 / 或 \\\\ JSON路径中
macOS brew install node@22 使用 /
Linux sudo apt install nodejs npm 或使用 非易失性存储器 使用 /

技术说明

  • Jira API版本：REST API v3-使用新的 GET /rest/api/3/search/jql 端点（旧 POST /search 是 已弃用并删除)
  • 认证：HTTP基本身份验证 email:api_token base64编码
  • 评论：张贴在Atlassian文档格式（ADF）；为了可读性，描述从ADF扁平化为纯文本
  • 缓存：在记忆中 Map-基于60s TTL的缓存；写入操作（例如添加注释）使相关缓存条目无效
  • 运输：仅限stdio（VS Code Copilot和JetBrains MCP集成所需）

许可证

麻省理工学院

相关 MCP