jira-mcp

Jira MCP 服务

最全面的 开源 Model Context Protocol（MCP） Jira 和 Atlassian 服务。几秒钟内即可将任何兼容 MCP 的 AI 客户端连接到你的 Jira 实例——无需离开 AI 助手，即可管理问题、冲刺、评论、状态转换、用户和 Confluence 页面。

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "raalarcon-jira-mcp-server"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

兼容的 AI 客户端

客户端	支持
Claude Desktop	✅
Claude Code	✅
Cursor	✅
Windsurf	✅
Cline	✅
Continue	✅
任何兼容 MCP 的客户端	✅

在以下平台查找此服务

• MCP Market — MCP 服务市场
• MCP Servers — 精选 MCP 服务目录
• Claude Marketplaces — Claude 插件和 MCP 目录
• npm — npx raalarcon-jira-mcp-server

功能

• ✅ 项目管理：列出项目和问题类型
• ✅ 问题增删改查：创建、读取、更新和删除问题
• ✅ 评论：创建、读取、更新和删除评论，并支持增强的分页功能
• ✅ 状态转换：在不同状态间移动问题
• ✅ 分配：将问题分配给用户
• ✅ 用户管理：搜索和管理用户
• ✅ 冲刺管理：完整管理敏捷冲刺生命周期
• ✅ Wiki 集成：通过 URL 标识符访问 Confluence 页面，并支持将 HTML 转换为文本
• ✅ 富文本支持：将 Markdown 转换为 ADF，以格式化描述和评论
• ✅ 验证：Yup 模式验证
• ✅ 身份验证：全面支持 Jira Cloud
• ✅ 优化的响应：通过字段筛选提高令牌使用效率
• ✅ 类型安全：全面支持 TypeScript

安装

选项 1：使用 npx（推荐）

使用此 MCP 服务最简单的方法是通过 npx：

1. 配置你的 MCP 客户端（例如 Claude Desktop），使用以下配置：

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "raalarcon-jira-mcp-server"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

2. 获取你的 Jira API 令牌（请参阅下方说明）

完成！需要时，服务将自动下载并运行。

选项 2：本地开发

1. 克隆仓库：

git clone https://github.com/raalarcon9705/jira-mcp.git
cd jira-mcp

2. 安装依赖项：

npm install

3. 构建项目：

npm run build

4. 配置你的 MCP 客户端，并填写构建后服务的完整路径：

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/full/path/to/jira-mcp/dist/index.js"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

注意：将 /full/path/to/jira-mcp/ 替换为项目目录的实际绝对路径。

获取 API 令牌

1. 前往 Atlassian 帐户设置
2. 点击“Create API token”
3. 为令牌填写一个描述性名称
4. 复制生成的令牌

用法

使用 npx（推荐）

在 MCP 客户端中完成配置后，服务器会在需要时自动启动。无需额外设置！

使用 Markdown 支持富文本

服务器现在支持自动将 Markdown 转换为 ADF，用于问题描述和评论。只需使用 Markdown 语法，内容便会自动转换为 Atlassian Document Format（ADF）。

支持的 Markdown 元素

• 标题：# H1、## H2、### H3
• 文本格式：**粗体**、*斜体*
• 代码：`行内代码` 和 代码块
• 列表：- 项目符号列表 和 1. 编号列表
• 链接：[文本](url)
• 引用块：> 引用文本
• 复选框：- [x] 已完成的任务

使用示例

// Create issue with Markdown description
create_issue({
  projectKey: 'PROJ',
  summary: 'Bug Report',
  description: `# Bug Report

## Description
This is a **critical** bug affecting the login system.

## Steps to Reproduce
1. Go to login page
2. Enter invalid credentials
3. Click login button

## Code Example
\`\`\`javascript
function login(username, password) {
  return authenticate(username, password);
}
\`\`\`

> **Note**: This bug was reported by multiple users.`,
});

// Create comment with Markdown
create_comment({
  issueKey: 'PROJ-123',
  body: `## Update

**Status**: Fixed ✅

- [x] Identified root cause
- [x] Implemented fix
- [x] Tested solution

The issue has been resolved.`,
});

开发

npm run dev

生产环境

npm run build
npm start

使用 npx 测试

你也可以直接使用 npx 测试服务器：

# Test the server
npx raalarcon-jira-mcp-server

# Or use with MCP Inspector
npx @modelcontextprotocol/inspector
# Then configure: command: "npx", args: ["-y", "raalarcon-jira-mcp-server"]

可用工具

项目

get_projects

获取已通过身份验证的用户有权访问的所有项目。

参数：

• expand（可选）：要包含的其他数据
• recent（可选）：最近项目的数量（0-20）

响应：包含必要字段的项目数组：

[
  {
    "key": "PROJ",
    "name": "Project Name",
    "id": "10001",
    "projectTypeKey": "software"
  }
]

get_issue_types

获取特定项目的所有可用问题类型。

参数：

• projectKey（必填）：项目键

响应：包含必要字段的问题类型数组：

[
  {
    "id": "10002",
    "name": "Task",
    "desc": "A small, independent piece of work",
    "subtask": false,
    "level": 0
  }
]

问题

create_issue

在 Jira 中创建新问题。

参数：

• projectKey（必填）：项目键
• summary（必填）：问题摘要
• issueType（必填）：问题类型（Bug、Story、Task 等）
• description（可选）：问题描述
• priority（可选）：优先级（Highest、High、Medium、Low、Lowest）
• assignee（可选）：经办人账户 ID
• labels（可选）：标签数组
• components（可选）：组件数组
• fixVersions（可选）：修复版本数组
• customFields（可选）：自定义字段值

响应：Issue PROJ-123 created successfully

get_issue

获取特定问题的详细信息（为节省令牌，会移除自定义字段）。

参数：

• issueKey（必填）：问题键（例如，PROJ-123）
• expand（可选）：其他信息
• fields（可选）：要返回的特定字段

响应：已筛除自定义字段的完整问题对象

update_issue

更新现有问题。

参数：

• issueKey（必填）：要更新的问题键
• summary（可选）：新摘要
• description（可选）：新描述
• priority（可选）：新优先级
• assignee（可选）：新经办人
• labels（可选）：新标签
• components（可选）：新组件
• fixVersions（可选）：新修复版本
• customFields（可选）：自定义字段

响应：Issue PROJ-123 updated successfully

delete_issue

删除问题。

参数：

• issueKey（必填）：要删除的问题键
• deleteSubtasks（可选）：同时删除子任务（默认值：false）

响应：Issue PROJ-123 deleted successfully

评论

create_comment

向问题添加评论。

参数：

• issueKey（必填）：问题键
• body（必填）：评论文本（支持 ADF 格式）
• visibility（可选）：可见性设置

响应：Comment 12345 created successfully

get_comments

获取问题的所有评论。

参数：

• issueKey（必填）：问题键
• startAt（可选）：起始索引（默认值：0）
• maxResults（可选）：评论数量上限（1-100，默认值：50）

响应：经过优化的评论结构：

{
  "total": 5,
  "start": 0,
  "max": 50,
  "items": [
    {
      "id": "12345",
      "author": "John Doe",
      "authorId": "account-id",
      "created": "2025-01-01T10:00:00.000Z",
      "text": "Comment text content"
    }
  ]
}

update_comment

更新现有评论。

参数：

• issueKey（必填）：问题键
• commentId（必填）：评论 ID
• body（必填）：新评论文本
• visibility（可选）：新的可见性设置

响应：Comment 12345 updated successfully

delete_comment

删除评论。

参数：

• issueKey（必填）：问题键
• commentId（必填）：评论 ID

响应：Comment 12345 deleted successfully

转换

get_transitions

获取问题的可用转换。

参数：

• issueKey（必填）：问题键

响应：包含必要字段的转换数组：

[
  {
    "id": "21",
    "name": "In Progress",
    "desc": "The assignee is currently working on this activity",
    "toName": "In Progress",
    "toId": "3",
    "available": true,
    "category": "In Progress"
  }
]

transition_issue

将问题转换为其他状态。

参数：

• issueKey（必填）：问题键
• transitionId（必填）：转换 ID
• comment（可选）：转换时添加的评论
• fields（可选）：要更新的其他字段

响应：Issue PROJ-123 transitioned successfully

分配

assign_issue

将问题分配给用户。

参数：

• issueKey（必填）：问题键
• assignee（必填）：用户账号 ID

响应：Issue PROJ-123 assigned successfully

get_users

搜索 Jira 中的用户。

参数：

• query（可选）：按姓名或电子邮件搜索的查询
• projectKey（可选）：按项目访问权限筛选
• maxResults（可选）：用户数量上限（1-100，默认值：50）

响应：包含必要字段的用户数组：

[
  {
    "id": "account-id",
    "name": "John Doe",
    "email": "[email protected]",
    "active": true,
    "type": "atlassian"
  }
]

get_current_user

获取当前经过身份验证的用户的信息。

响应：包含必要字段的当前用户信息：

{
  "id": "account-id",
  "name": "Current User",
  "email": "[email protected]",
  "active": true,
  "timezone": "America/New_York",
  "type": "atlassian"
}

Sprint 管理

get_agile_boards

获取 Jira 实例中所有可用的敏捷看板。查找 Sprint 操作所需的看板 ID。

参数：

• projectKey（可选）：按项目筛选看板
• boardType（可选）：按类型筛选（scrum、kanban）

响应：包含必要字段的看板数组：

[
  {
    "id": 191,
    "name": "DreamStar Board",
    "type": "scrum",
    "projectKey": "DRMSTR",
    "projectName": "DreamStar"
  }
]

get_sprints

获取指定看板的所有 Sprint。返回 Sprint 信息，包括 ID、名称、状态和日期。

参数：

• boardId（必填）：要获取其 Sprint 的看板 ID
• state（可选）：按状态筛选 Sprint（active、closed、future）

响应：包含必要字段的 Sprint 数组：

[
  {
    "id": 387,
    "name": "DRMSTR Sprint 1",
    "state": "active",
    "startDate": "2025-09-15T14:05:37.511Z",
    "endDate": "2025-09-26T05:00:00.000Z",
    "goal": ""
  }
]

create_sprint

创建新的 Sprint。必须提供 Sprint 名称和来源看板 ID。开始日期、结束日期和目标为可选项。

参数：

• name（必填）：要创建的 Sprint 名称
• originBoardId（必填）：要创建 Sprint 的看板 ID
• startDate（可选）：Sprint 开始日期（ISO 8601 格式）
• endDate（可选）：Sprint 结束日期（ISO 8601 格式）
• goal（可选）：Sprint 的目标或目的

响应：包含必要字段的已创建 Sprint：

{
  "id": 421,
  "name": "DRMSTR Sprint 3",
  "state": "future",
  "goal": ""
}

update_sprint

更新 Sprint 信息（名称、日期、目标、状态）。只会更新提供的字段。对于已关闭的 Sprint，只能更新名称和目标。

参数：

• sprintId（必填）：要更新的 Sprint ID
• name（可选）：Sprint 的新名称
• startDate（可选）：新的开始日期（ISO 8601 格式）
• endDate（可选）：新的结束日期（ISO 8601 格式）
• goal（可选）：Sprint 的新目标或目的
• state（可选）：新状态（future、active、closed）

响应：Sprint 421 updated successfully

close_sprint

关闭并完成 Sprint。此操作要求 Sprint 处于“active”状态。关闭后，无法重新打开 Sprint。

参数：

• sprintId（必填）：要关闭的 Sprint ID

响应：Sprint 421 closed successfully

delete_sprint

删除 Sprint。删除后，Sprint 中所有未解决的问题都会移至待办列表。此操作不可撤销。

参数：

• sprintId（必填）：要删除的 Sprint ID

响应：Sprint 421 deleted successfully. All open issues moved to backlog.

move_issue_to_sprint

将问题移至指定的冲刺。返回确认消息。问题只能移至未开始或进行中的冲刺。

参数：

• issueKey（必填）：要移动的问题键（例如，“PROJ-123”）
• sprintId（必填）：要将问题移至的冲刺 ID

响应：Issue PROJ-123 moved to sprint 421 successfully

get_sprint_issues

获取指定冲刺中的所有问题。返回问题的基本详细信息列表（键、摘要、状态、经办人、优先级）。

参数：

• sprintId（必填）：冲刺 ID
• maxResults（可选）：要返回的问题数量上限（1-100，默认值：50）

响应：包含基本字段的问题数组：

[
  {
    "key": "DRMSTR-1",
    "summary": "Implement user authentication",
    "status": "In Progress",
    "assignee": "John Doe",
    "priority": "High"
  }
]

响应优化

该服务针对令牌效率进行了优化：

• 仅返回基本字段：每项操作仅返回必要字段
• 筛除自定义字段：自动从问题响应中移除自定义字段
• 缩短字段名称：使用缩写字段名称（例如，使用 desc 代替 description）
• 成功消息：清晰简洁的成功确认消息
• 结构化数据：所有工具的响应格式保持一致

错误处理

该服务包含完善的错误处理机制，并提供描述性消息。常见错误包括：

• 身份验证：凭据无效或已过期
• 权限：执行操作的权限不足
• 验证：输入数据无效
• 资源：未找到问题或项目
• API：达到速率限制或 Jira 服务错误

开发

项目结构

src/
├── index.ts              # Main MCP server
├── jira-client.ts        # Jira API client
├── schemas/
│   └── index.ts          # Yup validation schemas
└── tools/
    ├── projects.ts       # Project tools
    ├── issues.ts         # Issue tools
    ├── comments.ts       # Comment tools
    ├── transitions.ts    # Transition tools
    ├── assignments.ts    # Assignment tools
    └── sprints.ts        # Sprint management tools

添加新功能

1. 在 src/schemas/index.ts 中创建验证架构
2. 在 src/jira-client.ts 中实现方法
3. 在 src/tools/ 中的相应文件里创建 MCP 工具
4. 在 src/index.ts 中注册工具

测试

使用 MCP Inspector（推荐）

1. 安装 MCP Inspector：

   npm install -g @modelcontextprotocol/inspector
   

2. 构建项目：

   npm run build
   

3. 启动 MCP Inspector：

   npx @modelcontextprotocol/inspector
   

4. 在 Inspector 界面中配置服务：

   • 传输方式：STDIO（默认）
   • 命令：node
   • 参数：build/index.js
   • 环境：添加你的 Jira 凭据

其他测试方法

命令行模式（用于自动化和脚本编写）：

# List available tools
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

# Call a specific tool
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/call --tool-name get_projects

配置文件（用于复杂配置）：

{
  "mcpServers": {
    "jira-server": {
      "command": "node",
      "args": ["build/index.js"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Claude Desktop：直接在 Claude Desktop 中配置 MCP 服务，以进行真实场景测试

高级配置

环境变量（适用于高级用户）：

# Jira configuration
export JIRA_HOST="https://your-domain.atlassian.net"
export JIRA_EMAIL="[email protected]"
export JIRA_API_TOKEN="your-api-token"

# Timeout settings
export MCP_SERVER_REQUEST_TIMEOUT=60000
export MCP_REQUEST_TIMEOUT_RESET_ON_PROGRESS=false

# Proxy settings (if using MCP Proxy)
export MCP_PROXY_FULL_ADDRESS=http://localhost:5577

# Auto-open browser
export MCP_AUTO_OPEN_ENABLED=true

查询参数（用于直接测试）：

http://localhost:6274/?transport=stdio&serverCommand=node&serverArgs=build/index.js

手动测试

# Build and run the server
npm run build
npm start

Wiki

query_wiki

通过 URL 标识符访问 Confluence 页面并返回格式化内容。

参数：

• query（必填）：要搜索的页面代码（例如 F4CjNw）

响应：包含元数据的 Markdown 格式页面内容：

# Page Title

**ID:** 933462039
**Space:** Orderbahn Team (OT)
**URL:** /spaces/OT/pages/933462039/...
**Author:** User Name
**Last Modified:** 2025-09-26T16:35:30.695Z
**Code:** F4CjNw

## Content

[Page content in plain text with preserved line breaks]

## Page Hierarchy

- Parent Page (page)
  - Child Page (folder)
    - Current Page (page)

功能：

• 自动跟随短 URL 重定向
• 将 HTML 转换为纯文本，同时保留结构
• 显示页面层级
• 完善的错误处理

贡献

欢迎为 Jira MCP Server 做出贡献！请遵循以下指南，确保贡献流程顺利进行。

开始

1. 在 GitHub 上复刻仓库
2. 在本地克隆你的复刻仓库：

   git clone https://github.com/raalarcon9705/jira-mcp.git
   cd jira-mcp
   

3. 安装依赖项：

   npm install
   

4. 为你的功能创建新分支：

   git checkout -b feature/your-feature-name
   

开发工作流

设置开发环境

1. 安装 MCP Inspector（官方测试工具）：

   npm install -g @modelcontextprotocol/inspector
   

2. 构建项目：

   npm run build
   

3. 使用 MCP Inspector 测试：

   npx @modelcontextprotocol/inspector
   

   然后配置你的服务：

   • 传输方式：STDIO
   • 命令：node
   • 参数：build/index.js
   • 环境：添加你的 Jira 凭据

代码规范

• TypeScript：所有代码必须使用 TypeScript 编写
• 类型安全：避免使用 any 类型，使用合适的 Jira.js 类型
• 错误处理：包含全面的错误处理
• 验证：使用 Yup 模式验证输入
• 注释：为复杂逻辑添加清晰的注释
• 格式：遵循现有的代码风格和格式

添加新功能

1. 创建验证模式，位于 src/schemas/index.ts：

   export const yourFeatureSchema = yup.object({
     // Define your schema
   });
   

2. 实现 API 方法，位于 src/jira-client.ts：

   async yourFeature(input: YourFeatureInput) {
     try {
       // Implementation
     } catch (error) {
       throw new Error(`Failed to your feature: ${error.message}`);
     }
   }
   

3. 在 src/tools/ 中的适当文件里创建 MCP 工具：

   {
     name: 'your_tool',
     description: 'Clear description of what the tool does',
     inputSchema: {
       // Define input schema
     }
   }
   

4. 在 src/index.ts 中注册工具：

   // Add to appropriate handler
   

5. 优化响应，提高令牌效率：

   • 仅返回必要字段
   • 使用较短的字段名
   • 过滤掉不必要的数据

测试你的更改

1. 构建项目：

   npm run build
   

2. 使用 MCP Inspector 测试：

   npx @modelcontextprotocol/inspector
   

   • 配置服务：STDIO，node build/index.js
   • 测试所有受影响的工具
   • 确认响应已优化

3. 使用 CLI 模式测试（用于自动化）：

   # List tools
   npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list
   
   # Test specific tool
   npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/call --tool-name get_projects
   

4. 验证响应优化：

   • 检查是否仅返回必要字段
   • 确认字段名已缩短
   • 确认已过滤自定义字段

Pull Request 流程

提交前

• 代码可编译，且没有 TypeScript 错误
• 所有工具均按预期工作
• 已实现响应优化
• 错误处理全面
• 必要时已更新文档
• 示例中不包含个人数据

创建 Pull Request

1. 使用清晰的说明提交更改：

   git add .
   git commit -m "Add new feature: brief description"
   

2. 推送到你的 fork：

   git push origin feature/your-feature-name
   

3. 在 GitHub 上创建 Pull Request，并包含：

   • 清晰的标题，说明更改内容
   • 详细说明，介绍新增或更改的内容
   • 测试说明，供审阅者参考
   • 如果涉及 UI 更改，附上截图

Pull Request 模板

## Description

Brief description of the changes

## Type of Change

- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing

- [ ] All existing tests pass
- [ ] New functionality tested
- [ ] Response optimization verified

## Checklist

- [ ] Code follows project standards
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No personal data included

代码审查流程

1. 自动检查会在你的 PR 上运行
2. 维护者会审查你的代码
3. 及时处理反馈
4. 按要求进行更改并更新 PR
5. 获批后合并 PR

报告问题

报告错误或请求新功能时：

1. 先检查现有问题
2. 使用提供的问题模板
3. 报告错误时，附上复现步骤
4. 请求新功能时，提供清晰的描述
5. 附上相关日志和错误消息

开发指南

响应优化

• 仅保留必要字段：只返回必要数据
• 使用较短的字段名：使用缩写名称（例如，用 desc 代替 description）
• 过滤自定义字段：从 issue 响应中移除 customfield_*
• 格式统一：保持响应结构一致

错误处理

• 描述性消息：在错误消息中包含上下文
• 恰当的错误类型：使用合适的错误类型
• 日志记录：添加 console.error 以便调试
• 便于用户理解：确保最终用户能理解错误信息

文档

• 更新 README：在文档中添加新工具
• 包含示例：提供用法示例
• 响应格式：说明响应结构
• 不含个人数据：仅使用通用示例

社区准则

• 在讨论中保持尊重并提供建设性意见
• 帮助他人学习和参与贡献
• 遵守行为准则
• 如需帮助，请提出问题

获取帮助

• GitHub Issues：用于报告错误和请求新功能
• 讨论区：用于提问和寻求一般帮助
• 文档：先查看现有文档
• 代码示例：参考现有实现

感谢你为 Jira MCP Server 做出贡献！🚀

🤝 贡献

欢迎社区成员贡献！本项目为开源项目，我们重视所有贡献。

贡献者快速入门

1. 在 GitHub 上 Fork 此仓库
2. 克隆你的 Fork：

   git clone https://github.com/your-username/jira-mcp.git
   cd jira-mcp
   

3. 安装依赖：

   npm install
   

4. 为你的功能创建分支：

   git checkout -b feature/your-feature-name
   

5. 进行修改并测试
6. 提交拉取请求

贡献方式

• 🐛 使用我们的错误报告模板报告错误
• ✨ 使用我们的功能请求模板请求功能
• 💻 提交代码改进和新功能
• 📚 改进文档和示例
• 🧪 添加测试以提高覆盖率
• 🌍 将文档翻译成其他语言

开发指南

• 遵循我们的贡献指南
• 阅读我们的行为准则
• 所有新代码都使用 TypeScript
• 为新功能添加测试
• 根据需要更新文档

获取帮助

• 💬 讨论：使用 GitHub Discussions 提问
• 🐛 问题：使用 GitHub Issues 报告错误和请求功能
• 📖 文档：查阅 README 和 CONTRIBUTING.md

发布到 npm

将此 MCP 服务发布到 npm，以便分发：

1. 登录 npm：

   npm login
   

2. 运行发布脚本：

   ./publish.sh
   

3. 或者手动发布：

   npm run build
   npm publish
   

此软件包将以 raalarcon-jira-mcp-server 的名称提供，用户可以通过以下命令安装：

npx raalarcon-jira-mcp-server

许可证

MIT

支持

如需报告错误或请求功能，请在仓库中提交 issue。

---

注意：此 MCP 服务专为 Jira Cloud 设计。对于 Jira Server/Data Center，身份验证和某些端点需要进行额外修改。