使用说明
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的客户端 | ✅ 完全支持 |
✨ 特性
🔐 认证
|
📋 问题管理
|
🏃 敏捷/Scrum
|
🔗 关系
|
⏱️ 时间跟踪
|
🗄️ 筛选器和元数据
|
📊 批量操作
|
📈 仪表板和JQL
|
91 Tools for comprehensive Jira management
📋 先决条件
运行时环境(选择一个)
| 🥟 Bun (Easier for beginners) | 📦 Node.js (Traditional) |
|---|---|
|
安装更简单,执行更快 安装Bun(一个命令): Windows(PowerShell作为管理员): macOS/Linux: |
使用更广泛,生态系统更大 要求:
|
Jira要求
| 要求 | 注意事项 |
|---|---|
| 吉拉云 | 不支持Jira服务器/数据中心 |
| Atlassian帐户 | 有权访问您的Jira实例 |
| API代币 | 在此处生成 |
MCP兼容客户端(其中之一)
- VS Code 使用GitHub Copilot扩展
- 克劳德桌面版 应用
- 光标 集成开发环境
- 帆板运动 集成开发环境
- 任何其他兼容MCP的AI助手
🚀 快速开始
安装
| 🥟 Using Bun (Recommended) | 📦 Using npm |
|---|---|
|
|
💡 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代币
- 首选 大西洋API代币
- 点击 创建API令牌
- 复制令牌
📘 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身份验证:
- 在中创建OAuth 2.0应用程序 Atlassian开发人员控制台
- 配置所需的作用域:
read:jira-workread:jira-userwrite:jira-workoffline_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
您的凭据无效或已过期。
对于基本身份验证:
- 在验证您的API令牌 大西洋API代币
- 确保令牌未被撤销
对于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(重大更改)
|
为安全起见:
|
改进:
|
📅 v2.x Changelog
v2.2.0版本
- 时间跟踪报告 -获取任何日期范围的用户工作日志及其摘要
v2.1.0
- 仪表板管理 -查看和管理Jira仪表板和小工具
- 增强附件 -上传附件,获取元数据和内容
- 标签管理 -获取所有标签,批量添加/删除/设置标签
- JQL工具 -自动完成、验证和解析JQL查询
v2.0.0版本
- 发出CRUD -在全面的现场支持下创建、更新问题
- 工作流转换 -通过工作流状态移动问题
- 敏捷/Scrum -完成冲刺和董事会管理(15个工具)
- 问题链接 -阻止、关联、复制关系
- 观众和投票 -协作功能
- Epic管理 -根据史诗组织问题
- 过滤器 -创建和管理已保存的JQL筛选器
- 元数据 -访问字段配置并创建元数据
- 批量操作 -一次编辑、观看、取消观看多个问题
🔒 安全
- 凭证通过系统钥匙链(Keytar)安全存储
- OAuth令牌在过期前自动刷新
- 错误消息中没有记录或公开凭据
- 看 安全.md 为了我们的安全政策
🤝 贡献
欢迎投稿!请参阅 贡献.md 作为指导方针。
- 分叉存储库
- 创建要素分支(
git checkout -b feature/amazing-feature) - 提交您的更改(
git commit -m 'Add amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
📄 更新日志
看 更改日志.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)