AI导哈

Jira问题管理工具

一个用于Cursor的Jira MCP服务器，支持通过URL或Issue Key获取Jira问题详情，支持JQL搜索和评论管理。

  • by saoqixiaomm
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 saoqixiaomm/jira-mcp

使用说明

Jira MCP Server

这是一个用于 Cursor 的 Jira MCP (Model Context Protocol) 服务器，可以让你在 Cursor 中直接通过 Jira URL 或 Issue Key 获取 Jira Issue 的详细信息。

✨ 支持的 Jira 版本:

  • ☁️ Jira Cloud（云版本）
  • 🏢 Jira Server/Data Center（本地部署版本）

功能特性

✨ 核心功能:

  • 📋 通过 Jira URL 或 Issue Key 获取 Issue 详情
  • 🔍 使用 JQL (Jira Query Language) 搜索 Issues
  • 💬 可选择是否包含评论信息
  • 📝 支持 Atlassian Document Format (ADF) 格式的描述解析
  • 🌳 显示父任务和子任务关系
  • 🔗 支持相关链接、附件等完整信息

安装步骤

1. 安装依赖

cd jira-mcp
npm install

2. 配置环境变量

创建 .env 文件（可以复制 .env.example）:

cp .env.example .env

编辑 .env 文件，根据你的 Jira 类型选择相应的配置：

方式 A: Jira Cloud（云版本）

JIRA_BASE_URL=https://your-domain.atlassian.net
JIRA_EMAIL=your-email@example.com
JIRA_API_TOKEN=your-jira-api-token

如何获取 API Token:

  1. 访问 Atlassian API Tokens
  2. 点击 "Create API token"
  3. 输入标签名称（例如：cursor-mcp）
  4. 复制生成的 token

方式 B: Jira Server/Data Center（本地部署版本）

JIRA_BASE_URL=https://jira.yourcompany.com
JIRA_USERNAME=your-username
JIRA_API_TOKEN=your-personal-access-token

如何获取 Personal Access Token:

  1. 登录你的 Jira Server
  2. 点击右上角头像 → Profile
  3. 左侧菜单选择 Personal Access Tokens
  4. 点击 Create token
  5. 输入 Token 名称和有效期
  6. 复制生成的 token

⚠️ 重要提示:

  • JIRA_USERNAME 应该是你的用户名，不要包含域名
    • ✅ 正确: wangmeng
    • ❌ 错误: wangmeng@xxxxx.com

3. 构建项目

npm run build

4. 测试配置（可选）

在配置 Cursor 之前，建议先测试 Jira 连接是否正常：

node test-config.js

如果配置正确，你会看到 "✅ 配置验证成功！" 的提示。

配置 Cursor MCP

方式一：使用环境变量文件（推荐）

如果你已经配置了 .env 文件，可以使用以下配置：

配置文件位置：

  • macOS/Linux: ~/.config/cursor/mcp.json
  • Windows: %APPDATA%\cursor\mcp.json

编辑配置文件，添加以下内容：

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/absolute/path/to/guanlink-mcp/jira-mcp/dist/index.js"]
    }
  }
}

注意:

  • 将路径替换为你的实际项目路径（必须是绝对路径）
  • 服务器会自动读取项目目录下的 .env 文件

方式二：直接在配置中指定环境变量

Jira Cloud 配置示例：

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/absolute/path/to/guanlink-mcp/jira-mcp/dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-jira-api-token"
      }
    }
  }
}

Jira Server 配置示例：

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/absolute/path/to/guanlink-mcp/jira-mcp/dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://jira.yourcompany.com",
        "JIRA_USERNAME": "your-username",
        "JIRA_API_TOKEN": "your-personal-access-token"
      }
    }
  }
}

启动服务

  1. 保存配置文件
  2. 重启 Cursor 使配置生效
  3. 在 Cursor 中，你应该能看到 Jira MCP 服务已连接

部署给其他用户

方式一：共享配置模板

  1. 将 cursor-mcp-config.json 配置模板分享给用户

  2. 用户需要修改以下内容：

    • args 中的路径改为实际部署路径
    • JIRA_USERNAME 改为用户自己的 Jira 用户名
    • JIRA_API_TOKEN 改为用户自己的 Personal Access Token

  3. 用户将配置添加到自己的 ~/.config/cursor/mcp.json (macOS/Linux) 或 %APPDATA%\cursor\mcp.json (Windows)

方式二：服务器部署

如果部署到服务器供团队使用：

  1. 在服务器上克隆项目

    git clone <your-repo>
cd jira-mcp
npm install
npm run build

  2. 每个用户在自己的 Cursor 配置中指定服务器地址

    用户的 ~/.config/cursor/mcp.json:

    {
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/shared/path/to/jira-mcp/dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://jira.yourcompany.com",
        "JIRA_USERNAME": "user-specific-username",
        "JIRA_API_TOKEN": "user-specific-token"
      }
    }
  }
}

  3. 团队成员获取自己的 Token

    • 登录 Jira Server: https://jira.yourcompany.com
    • 右上角头像 → Profile
    • Personal Access Tokens → Create token
    • 将生成的 token 填入配置

安全建议

⚠️ 重要提示:

  • 不要在代码仓库中提交包含真实 token 的配置文件
  • 每个用户应该使用自己的 Jira 账号和 token
  • 定期更新 Personal Access Token
  • 如果 token 泄露，立即在 Jira 中撤销

使用方法

配置完成后，重启 Cursor，你就可以在 Cursor 中使用 Jira MCP 服务了。

示例 1: 获取 Issue 详情

在 Cursor 中输入:

请帮我获取这个 Jira Issue 的信息：https://your-domain.atlassian.net/browse/PROJECT-123

或者直接使用 Issue Key:

请帮我查看 PROJECT-123 这个 Issue

示例 2: 包含评论

请获取 PROJECT-123 的详细信息，包括评论

示例 3: 搜索 Issues

请搜索所有分配给我且状态为进行中的 Issues

Cursor 会自动调用 MCP 工具，使用 JQL: assignee = currentUser() AND status = "In Progress"

示例 4: 使用 JQL 搜索

请搜索最近 7 天创建的高优先级 Issues

MCP 工具说明

1. get-jira-issue

获取单个 Jira Issue 的详细信息。

参数:

  • issueKeyOrUrl (string, 必需): Jira Issue Key 或完整 URL
  • includeComments (boolean, 可选): 是否包含评论，默认 false

支持的 URL 格式:

  • https://your-domain.atlassian.net/browse/PROJECT-123
  • https://your-domain.atlassian.net/jira/software/projects/PROJECT/boards/1?selectedIssue=PROJECT-123

返回信息:

  • Issue 基本信息（Key、标题、状态、类型、优先级）
  • 项目信息
  • 经办人和报告人
  • 创建和更新时间
  • 标签、组件、修复版本
  • 描述内容（支持 ADF 格式）
  • 父任务和子任务
  • 评论（如果启用）

2. search-jira-issues

使用 JQL 搜索 Jira Issues。

参数:

  • jql (string, 必需): JQL 查询语句
  • maxResults (number, 可选): 最大返回结果数，默认 50，最大 100

JQL 示例:

project = PROJECT AND status = "In Progress"
assignee = currentUser() AND status != Done
created >= -7d
text ~ "关键词"
priority = High AND assignee is EMPTY

更多 JQL 语法请参考: Jira JQL 文档

开发

项目结构

jira-mcp/
├── src/
│   ├── index.ts           # MCP 服务器入口
│   └── lib/
│       ├── api.ts         # Jira API 调用
│       ├── types.ts       # TypeScript 类型定义
│       └── utils.ts       # 工具函数（URL 解析、格式化等）
├── dist/                  # 编译输出目录
├── package.json
├── tsconfig.json
├── .env.example          # 环境变量示例
└── README.md

开发命令

# 安装依赖
npm install

# 构建
npm run build

# 开发模式（构建并运行）
npm run dev

# 格式化代码
npm run format

# 代码检查
npm run lint

故障排除

1. 认证失败 (401 Unauthorized)

Jira Cloud:

  • ✅ 检查 JIRA_EMAIL 是否正确（应该是完整的邮箱地址）
  • ✅ 检查 JIRA_API_TOKEN 是否有效
  • ✅ 确认在 Atlassian 账号管理页面创建了 API Token

Jira Server:

  • ✅ 检查 JIRA_USERNAME 是否正确（不要包含域名）
    • ✅ 正确: your-username
    • ❌ 错误: your-username@company.com
  • ✅ 检查 Personal Access Token 是否有效且未过期
  • ✅ 确认在 Jira Profile 中创建了 Personal Access Token

2. 无法连接到 Jira

检查项:

  • ✅ JIRA_BASE_URL 是否正确（不要包含尾部斜杠）
    • ✅ 正确: https://jira.yourcompany.com
    • ❌ 错误: https://jira.yourcompany.com/
  • ✅ 网络连接是否正常
  • ✅ 是否能在浏览器中访问 Jira 地址

3. 权限错误

确保你的 Jira 账号有权限访问相应的 Project 和 Issue。

4. Issue 不存在

检查 Issue Key 是否正确，以及你是否有权限查看该 Issue。

5. Cursor 无法找到 MCP 服务

  • ✅ 检查 mcp.json 中的路径是否正确（必须是绝对路径）
  • ✅ 确保已经运行 npm run build 构建项目
  • ✅ 检查 dist/index.js 文件是否存在
  • ✅ 重启 Cursor

6. 如何判断 Jira 类型

  • Jira Cloud: URL 类似 https://xxx.atlassian.net
  • Jira Server: URL 是自定义域名，如 https://jira.yourcompany.com 或 https://task.xxxxx.com

可以访问 https://your-jira-url/rest/api/2/serverInfo 查看服务器信息：

curl https://your-jira-url/rest/api/2/serverInfo

返回的 deploymentType 字段会显示是 Cloud 还是 Server。

技术栈

  • TypeScript: 类型安全的 JavaScript
  • @modelcontextprotocol/sdk: MCP 协议 SDK
  • undici: 高性能 HTTP 客户端
  • zod: 运行时类型验证
  • Jira REST API v2: 兼容 Jira Cloud 和 Jira Server/Data Center

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

相关链接

后续计划

  • [ ] 支持语雀 (Yuque) 集成
  • [ ] 支持创建和更新 Issue
  • [ ] 支持添加评论
  • [ ] 支持获取 Sprint 信息
  • [ ] 支持获取 Board 信息
  • [ ] 缓存机制优化性能

如有问题或建议，欢迎联系！

相关 MCP