Jira集成工具

一个基于Model Context Protocol (MCP)的服务,使AI助手能够与Jira Cloud实例无缝交互,支持问题搜索、工单管理、工作时间记录等功能。

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

使用说明

Jira MCP Server

Supercharge your AI assistant with seamless Jira integration

Quick Start • Features • Configuration • Tools • Examples • Troubleshooting


A. 模型上下文协议(MCP) 支持AI助手的服务器,如 GitHub Copilot 和 克劳德 与您的Jira Cloud实例进行交互。搜索问题、管理工单、记录工作等,所有这些都是通过自然语言对话完成的。

🎯 为什么使用这个包?

不带MCP 带Jira MCP
在IDE和浏览器之间切换 留在您的编码环境中
手动复制粘贴问题详情 AI自动获取上下文
学习JQL语法 自然语言查询
点击Jira UI 语音/文本命令
上下文切换会降低生产力 无缝工作流集成

支持的AI助手

助理 状态
GitHub副本(VS代码) ✅ 完全支持
克劳德桌面 ✅ 完全支持
光标 ✅ 完全支持
风浪 ✅ 完全支持
任何兼容MCP的客户端 ✅ 完全支持

✨ 特性

🔐 认证

  • 基本身份验证(API令牌)
  • OAuth 2.0自动刷新
  • 通过Keytar实现安全凭证存储

📋 问题管理

  • 完整的CRUD操作
  • 工作流转换
  • 使用JQL搜索

🏃 敏捷/Scrum

  • Sprint管理(创建、启动、完成)
  • 董事会视图(Scrum和看板)
  • 积压和排名

🔗 关系

  • 问题链接(阻止、关联、重复)
  • 观察者和投票
  • Epic管理

⏱️ 时间跟踪

  • 记录问题工作
  • 查看工作日志
  • 按用户和日期范围查询工作日志
  • 灵活的时间格式

🗄️ 筛选器和元数据

  • 创建/管理已保存的筛选器
  • 字段元数据访问
  • 组件和版本管理

📊 批量操作

  • 批量编辑问题
  • 散装手表/无手表
  • 异步操作跟踪

📈 仪表板和JQL

  • 仪表板管理
  • JQL验证和自动完成
  • 标签管理

91 Tools for comprehensive Jira management

📋 先决条件

运行时环境(选择一个)

🥟 Bun (Easier for beginners) 📦 Node.js (Traditional)

安装更简单,执行更快

安装Bun(一个命令):

Windows(PowerShell作为管理员):

irm bun.sh/install.ps1 | iex

macOS/Linux:

curl -fsSL https://bun.sh/install | bash

使用更广泛,生态系统更大

要求:

  • Node.js≥18.0.0(下载)
  • npm≥8.0.0(包含在Node.js中)

Jira要求

要求 注意事项
吉拉云 不支持Jira服务器/数据中心
Atlassian帐户 有权访问您的Jira实例
API代币 在此处生成

MCP兼容客户端(其中之一)

  • VS Code 使用GitHub Copilot扩展
  • 克劳德桌面版 应用
  • 光标 集成开发环境
  • 帆板运动 集成开发环境
  • 任何其他兼容MCP的AI助手

🚀 快速开始

安装

🥟 Using Bun (Recommended) 📦 Using npm
# Run directly (no install needed)
bunx mcp-jira-cloud@latest

# Or install globally
bun install -g mcp-jira-cloud
# Run directly (no install needed)
npx -y mcp-jira-cloud@latest

# Or install globally
npm install -g mcp-jira-cloud

💡 CLI帮助

要查看所有可用选项和配置详细信息:

npx -y mcp-jira-cloud@latest --help

要启动交互式设置助手(生成MCP配置JSON):

npx -y mcp-jira-cloud@latest --config

要验证您的Jira连接和凭据:

npx -y mcp-jira-cloud@latest --verify

要启用诊断日志记录(将API流量记录到stderr),请执行以下操作:

npx -y mcp-jira-cloud@latest --verbose

获取您的API代币

  1. 首选 大西洋API代币
  2. 点击 创建API令牌
  3. 复制令牌

📘 VS代码(GitHub副本)

创建或编辑 .vscode/mcp.json 在您的工作空间中:

🥟 Using Bun (recommended for beginners)
{
  "servers": {
    "jira": {
      "type": "stdio",
      "command": "bunx",
      "args": ["mcp-jira-cloud@latest"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}
📦 Using npx
{
  "servers": {
    "jira": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-jira-cloud@latest"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}
⚡ After global install
{
  "servers": {
    "jira": {
      "type": "stdio",
      "command": "jira-mcp",
      "args": [],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

🤖 克劳德桌面版

添加到您的Claude配置(claude_desktop_config.json):

🥟 Using Bun (recommended for beginners)
{
  "mcpServers": {
    "jira": {
      "command": "bunx",
      "args": ["mcp-jira-cloud@latest"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}
📦 Using npx
{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "mcp-jira-cloud@latest"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

⚡ 光标

创建 .cursor/mcp.json 在您的项目或主目录中:

🥟 Using Bun (recommended for beginners)
{
  "mcpServers": {
    "jira": {
      "command": "bunx",
      "args": ["mcp-jira-cloud@latest"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}
📦 Using npx
{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "mcp-jira-cloud@latest"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}
⚡ After global install
{
  "mcpServers": {
    "jira": {
      "command": "jira-mcp",
      "args": [],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

🔧 帆板运动

添加到您的Windsurf MCP配置中:

🥟 Using Bun (recommended for beginners)
{
  "mcpServers": {
    "jira": {
      "command": "bunx",
      "args": ["mcp-jira-cloud@latest"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}
📦 Using npx
{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "mcp-jira-cloud@latest"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}
⚡ After global install
{
  "mcpServers": {
    "jira": {
      "command": "jira-mcp",
      "args": [],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

⚙️ 配置

环境变量

基本身份验证(推荐)

变量 描述 必填
JIRA_BASE_URL 您的Jira实例URL(例如。, https://company.atlassian.net) ✅
JIRA_EMAIL 您的Atlassian帐户电子邮件 ✅
JIRA_API_TOKEN Atlassian的API令牌 ✅

OAuth 2.0身份验证

Click to expand OAuth configuration

对于OAuth身份验证:

  1. 在中创建OAuth 2.0应用程序 Atlassian开发人员控制台
  2. 配置所需的作用域:
    • read:jira-work
    • read:jira-user
    • write:jira-work
    • offline_access
变量 描述 必填
JIRA_OAUTH_CLIENT_ID OAuth客户端ID ✅
JIRA_OAUTH_CLIENT_SECRET OAuth客户端密码 ✅
JIRA_OAUTH_ACCESS_TOKEN 访问令牌 ✅
JIRA_OAUTH_REFRESH_TOKEN 刷新令牌 ⬜
JIRA_CLOUD_ID 您的Jira Cloud ID ✅

可选设置

变量 描述 默认值
JIRA_ACCEPTANCE_CRITERIA_FIELD 验收标准的自定义字段ID --

🛠️ 可用工具

91工具 分为11类

🔐 身份验证(7个工具)

工具 说明
jira_auth_status 检查当前身份验证状态
jira_whoami 获取当前用户的Jira个人资料
jira_clear_auth 清除存储的凭据
jira_oauth_get_auth_url 生成OAuth授权URL
jira_oauth_exchange_code 用OAuth代码交换令牌
jira_oauth_refresh 手动刷新OAuth令牌
jira_oauth_list_sites 列出可访问的Jira网站

📝 发布CRUD(5个工具)

工具 说明
jira_create_issue 在全面的现场支持下创建新问题
jira_update_issue 更新问题字段(支持部分更新)
jira_assign_issue 分配或取消分配用户
jira_get_transitions 获取可用的工作流转换
jira_transition_issue 通过工作流状态移动问题

🔍 问题查询(6个工具)

工具 说明
jira_get_issue 获取Jira问题的完整详细信息(标签、状态、优先级、受让人、组件等);通过 fields 返回特定子集
jira_get_issue_summary 获取摘要、描述和验收标准
jira_search_issues 使用JQL搜索问题,返回完整字段详细信息(通过 fields 对于特定子集)
jira_search_issues_summary 使用最少的字段(关键字、摘要、状态)进行搜索
jira_get_my_open_issues 获取您的未决/进行中问题
jira_resolve 用于常见意图的智能路由工具

💬 评论和工作日志(5个工具)

工具 说明
jira_get_issue_comments 获取对某个问题的评论
jira_add_comment 向问题添加评论
jira_add_worklog 记录在问题上花费的时间
jira_get_issue_worklogs 获取问题的工作日志
jira_get_user_worklogs 按用户和日期范围获取工作日志

⚙️ 配置和元数据(9个工具)

工具 说明
jira_list_projects 列出可访问的Jira项目
jira_get_project 获取项目详细信息和元数据
jira_get_issue_types 获取可用的问题类型
jira_get_priorities 获取优先级
jira_get_statuses 获取可用状态
jira_get_components 获取项目组件
jira_get_versions 获取项目版本
jira_search_users 搜索Jira用户
jira_get_changelog 获取问题更改历史记录
🏃 Agile/Sprint Tools (15 tools)
工具 说明
jira_get_boards 列出Scrum和看板
jira_get_board 获取电路板详细信息
jira_get_board_configuration 获取板配置(列、估计)
jira_get_sprints 冲刺板
jira_get_sprint 获取冲刺详细信息
jira_create_sprint 创建一个新的sprint
jira_update_sprint 更新冲刺详细信息
jira_start_sprint 开始未来的冲刺
jira_complete_sprint 完成一次主动冲刺
jira_get_sprint_issues 在冲刺中解决问题
jira_move_issues_to_sprint 将问题转移到冲刺阶段
jira_get_backlog_issues 为董事会处理积压问题
jira_move_issues_to_backlog 将问题移至待办事项列表
jira_rank_issues 更改问题排名
🔗 Issue Relationships (9 tools)
工具 说明
jira_get_issue_links 获取链接问题
jira_create_issue_link 将两个问题联系在一起
jira_get_link_types 获取可用链接类型
jira_get_watchers 获取问题观察者
jira_add_watcher 向问题添加观察者
jira_remove_watcher 删除观察者
jira_get_votes 获取问题投票计数
jira_add_vote 为某个问题投票
jira_remove_vote 删除您的投票
Epic Management (4 tools)
工具 说明
jira_get_epics 为棋盘拍摄史诗
jira_get_epic_issues 获取属于史诗的问题
jira_move_issues_to_epic 将问题转化为史诗
jira_remove_issues_from_epic 从史诗中删除问题
🗂️ Field Metadata (3 tools)
工具 说明
jira_get_fields 获取所有可用字段(包括自定义字段)
jira_get_create_metadata 获取用于创建问题的元数据
jira_get_edit_metadata 获取编辑问题的元数据
🗄️ Filters (6 tools)
工具 说明
jira_get_filters 搜索已保存的筛选器
jira_get_filter 获取过滤器详细信息
jira_create_filter 创建新的已保存筛选器
jira_update_filter 更新现有筛选器
jira_get_my_filters 获取您拥有的过滤器
jira_get_favourite_filters 获取喜爱的过滤器
⚡ Bulk Operations (4 tools)
工具 说明
jira_bulk_edit_issues 一次编辑多个问题(标签、受让人、优先级等)
jira_bulk_watch_issues 为多个问题添加观察者
jira_bulk_unwatch_issues 从多个问题中删除观察者
jira_get_bulk_operation_progress 跟踪异步批量操作进度
📊 Dashboard Management (5 tools)
工具 说明
jira_get_dashboards 获取仪表板(按收藏/拥有进行筛选)
jira_search_dashboards 按名称、所有者等搜索仪表板。
jira_get_dashboard 按ID获取仪表板详细信息
jira_get_dashboard_gadgets 在仪表板上获取所有小工具
jira_add_dashboard_gadget 将小工具添加到仪表板
📎 Enhanced Attachments (4 tools)
工具 说明
jira_get_attachments 获取问题附件
jira_upload_attachment 将文件上传到问题
jira_get_attachment_metadata 按ID获取附件元数据
jira_get_attachment_content 获取附件下载URL
🏷️ Labels Management (2 tools)
工具 说明
jira_get_all_labels 获取Jira实例中的所有标签
jira_add_labels 添加、设置或删除问题标签
🔎 JQL Tools (3 tools)
工具 说明
jira_autocomplete_jql 获取JQL字段的自动补全建议
jira_validate_jql 验证JQL查询是否存在语法错误
jira_parse_jql 将JQL解析为抽象语法树
⏱️ Time Tracking Reports (4 tools)
工具 说明
jira_get_updated_worklog_ids 获取自某个日期以来创建/更新的工作日志ID
jira_get_worklogs_by_ids 按ID获取完整的工作日志详细信息(批量最多1000个)
jira_get_user_worklogs 获取日期范围内用户的所有工作日志及其摘要
jira_get_deleted_worklog_ids 获取已删除工作日志的ID以供审计

🛡️ 第14阶段:代码质量和安全

此版本经过了全面审核,以确保最佳实践和安全性:

类别 状态 详细信息
API版本 ✅ 所有91个工具都使用Jira REST API v3(最新版本)
敏捷API ✅ Sprint/Board工具使用Jira Agile API v1.0
弃用的API ✅ 所有弃用的端点都迁移到了现代替代方案
安全漏洞 ✅ 0个漏洞(已修补axios和qs)
OAuth 2.0支持 ✅ 具有自动刷新功能的完整OAuth 2.0(3LO)
凭据存储 ✅ 通过Keytar进行操作系统级加密
输入验证 ✅ 对所有参数进行Zod v4模式验证
URL译码 ✅ 所有动态路径参数均已正确编码
错误处理 ✅ 跨所有端点的一致错误处理

💡 使用示例

配置后,通过自然对话与Jira交互:

问题管理

👤 "What's the status of PROJ-123?"
🤖 Fetches and displays issue details, status, and assignee

👤 "Create a bug in PROJ for 'Login button not working'"
🤖 Creates a new bug issue and returns the issue key

👤 "Assign PROJ-456 to john@example.com"
🤖 Assigns the issue to the specified user

👤 "Move PROJ-789 to 'In Progress'"
🤖 Transitions the issue to the new status

Sprint&敏捷

👤 "Show me the active sprint for board 123"
🤖 Displays current sprint details with dates and goal

👤 "Move PROJ-123 and PROJ-124 to sprint 456"
🤖 Moves the issues to the specified sprint

👤 "What's in the backlog for the PROJ board?"
🤖 Lists all backlog issues with priorities

时间跟踪

👤 "Log 2 hours on PROJ-456 for code review"
🤖 Creates work log entry with description

👤 "How much time has been logged on PROJ-789?"
🤖 Retrieves and summarises work logs

协作

👤 "Link PROJ-123 as blocking PROJ-456"
🤖 Creates a "blocks" relationship between issues

👤 "Add me as a watcher on PROJ-789"
🤖 Adds you to the issue's watch list

👤 "Show all issues in epic PROJ-100"
🤖 Lists all child issues of the epic

🔧 故障排除

🥟 Bun Installation Issues

Windows(PowerShell作为管理员):

# If irm fails, try:
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm bun.sh/install.ps1 | iex

macOS/Linux:

# If curl fails, check your internet connection or try:
brew install oven-sh/bun/bun  # macOS with Homebrew

验证安装:

bun --version  # Should show 1.x.x
❌ "MISSING_AUTH" Error

确保您的环境变量设置正确。验证 jira_auth_status.

检查表:

  • ✅ JIRA_BASE_URL 包括 https:// 并且是您的完整Jira域名
  • ✅ JIRA_EMAIL 匹配您的Atlassian帐户电子邮件
  • ✅ JIRA_API_TOKEN 是一个有效的、未过期的令牌
❌ "401 Unauthorised" Error

您的凭据无效或已过期。

对于基本身份验证:

对于OAuth:

  • 尝试用以下命令刷新令牌 jira_oauth_refresh
  • 如果刷新令牌已过期,则重新进行身份验证
❌ "403 Forbidden" Error

您没有访问所请求资源的权限。

解决:

  • 检查项目的Jira权限
  • 联系您的Jira管理员
  • 验证您的OAuth作用域是否包含所需权限
❌ "404 Not Found" Error

问题或项目不存在,或者您没有查看它的权限。

解决:

  • 验证问题密钥是否正确(例如。, PROJ-123)
  • 检查您是否有权访问该项目
  • 确保问题未被删除或移动
❌ npx/bunx Using Old Version

清除缓存以确保获得最新版本:

npm:

npx -y --package=mcp-jira-cloud@latest mcp-jira-cloud
# or clear cache:
npm cache clean --force

面包:

bunx --bun mcp-jira-cloud@latest
# or clear cache:
bun pm cache rm

📦 包裹信息

属性 值
包名称 mcp-jira-cloud
最新版本
许可证 麻省理工学院
运行时 Bun≥1.0.0或Node.js≥18.0.0
TypeScript ≥5.0.0
模块 ES模块
工具 91

依赖项

包装 用途
@modelcontextprotocol/sdk MCP协议实现
axios Jira API的HTTP客户端
keytar 安全的凭证存储
zod 架构验证

🆕 最新动态

🐛 v4.3.2(最新版本)

修复 说明
🏷️ 全场透传 jira_get_issue & jira_search_issues 现在返回所有请求的字段-- labels, status, priority, assignee, components, fixVersions、自定义字段等。--而不仅仅是 key/summary/description (#2)
📋 有用的默认值 何时 fields 如果省略,完整细节工具现在返回一个广泛的默认集;精简摘要工具保持其精简的输出
🧹 紧凑,无需制造 嵌套对象被规范化为友好值(status→name, assignee→显示名称、…)和未请求的字段从未被发明

🚀 v4.3.0

特性 描述
🧩 模块化架构 工具重构为模块化、有组织的文件(src/tools/)
🚀 扩展工具集 现在有91个工具,包括新的敏捷、工作日志和元数据功能
🛡️ 改进的工具 标准化身份验证(withClient)&注释预设
✅ 测试套件 集成Vitest,实现跨代码库的稳健单元测试

🥟 v4.2.0

特性 描述
🥟 Bun支持 跑步 bunx mcp-jira-cloud@latest -对初学者来说更容易
📖 更好的文档 简化的先决条件和配置示例

🔍 v4.1.0

特性 描述
🎯 改进的工具描述 更好的触发短语、负面指导和人工智能代理的交叉引用
📋 先决条件部分 README中记录的明确要求

🚀 v4.0.0

更改 描述
⚠️ 霹雳舞 jira_get_worklogs 命名至 jira_get_issue_worklogs 为清楚起见
🐛 修复 删除了导致启动错误的重复工具注册

工具总数:74


📦 v3.1.0

特性 描述
🔍 用户工作日志查询 新 jira_get_user_worklogs 按用户和日期范围查询工作日志的工具
📊 时间总结 返回记录的总时间,格式为小时/分钟

⚠️ v3.0.0(重大更改)

为安全起见:

  • jira_delete_issue
  • jira_delete_sprint
  • jira_delete_attachment
  • jira_delete_filter
  • jira_delete_issue_link

改进:

  • 🔒 安全补丁(axios、qs)
  • 🔄 不推荐的API迁移
  • ✅ 0个已知漏洞

📅 v2.x Changelog

v2.2.0版本

  • 时间跟踪报告 -获取任何日期范围的用户工作日志及其摘要

v2.1.0

  • 仪表板管理 -查看和管理Jira仪表板和小工具
  • 增强附件 -上传附件,获取元数据和内容
  • 标签管理 -获取所有标签,批量添加/删除/设置标签
  • JQL工具 -自动完成、验证和解析JQL查询

v2.0.0版本

  • 发出CRUD -在全面的现场支持下创建、更新问题
  • 工作流转换 -通过工作流状态移动问题
  • 敏捷/Scrum -完成冲刺和董事会管理(15个工具)
  • 问题链接 -阻止、关联、复制关系
  • 观众和投票 -协作功能
  • Epic管理 -根据史诗组织问题
  • 过滤器 -创建和管理已保存的JQL筛选器
  • 元数据 -访问字段配置并创建元数据
  • 批量操作 -一次编辑、观看、取消观看多个问题

🔒 安全

  • 凭证通过系统钥匙链(Keytar)安全存储
  • OAuth令牌在过期前自动刷新
  • 错误消息中没有记录或公开凭据
  • 看 安全.md 为了我们的安全政策

🤝 贡献

欢迎投稿!请参阅 贡献.md 作为指导方针。

  1. 分叉存储库
  2. 创建要素分支(git checkout -b feature/amazing-feature)
  3. 提交您的更改(git commit -m 'Add amazing feature')
  4. 推到分支(git push origin feature/amazing-feature)
  5. 打开拉取请求

📄 更新日志

看 更改日志.md 查看每个版本的更改列表。

📜 许可证

该项目根据 MIT许可证 --看看 许可证 文件以获取详细信息。

🔗 链接

资源 链接
GitHub github/tezaswiraj7222/jira-mcp
npm npmjs.com/package/mcp-jira云
问题 报告错误
MCP协议 模型上下文协议.io
Jira API Jira REST API v3

Made with ❤️ by Tezaswi Raj (github: tezaswiraj7222)