Jira MCP Server

Jira MCP 服务

增强型模型上下文协议服务，可通过 Claude 直接与 Jira 交互。

此服务允许启用了模型上下文协议的 AI 助手（如 Claude）直接与 Jira 实例交互，以执行各种项目管理任务，包括：

• 获取项目信息和问题
• 创建和更新问题及子任务
• 管理问题工作流和状态转换
• 创建问题链接和依赖关系
• 添加评论并管理问题字段
• 用户管理和分配
• 高效管理问题的批量操作

功能

• 完整的 Jira API 集成：全面访问 Jira 功能
• 增强的格式支持：改进 Markdown 到 Atlassian 文档格式（ADF）的转换，并支持代码块和行内格式
• 输入验证：使用 Zod 进行稳健的架构验证
• 改进的错误处理：提供详细的错误消息，并在发生错误时优雅地恢复
• 自定义字段支持：轻松配置自定义 Jira 字段
• 状态转换：高级工作流管理
• 批量操作：支持问题的批量操作（更新、删除）
• 精细的标签／组件管理：添加、移除或替换标签和组件
• 可配置的日志记录：通过环境变量控制日志详细程度

先决条件

• Node.js 18 或更高版本
• Jira Cloud 或 Server 实例
• Jira API 令牌（适用于 Cloud）或用户名／密码（适用于 Server）
• Claude Desktop 或其他兼容 MCP 的 AI 助手

安装

1. 克隆此仓库：

   git clone https://github.com/yourusername/jira-server.git
   cd jira-server
   

2. 安装依赖项：

   npm install
   

3. 设置环境变量：

   cp .env.example .env
   

4. 使用 Jira 凭据编辑 .env 文件：

   JIRA_HOST=your-instance.atlassian.net
   [email protected]
   JIRA_API_TOKEN=your-api-token
   

5. 构建服务：

   npm run build
   

使用方法

启动服务

npm start

开发模式

用于支持自动重新加载的开发模式：

npm run dev

代码检查和格式化

# Run ESLint
npm run lint

# Format code with Prettier
npm run format

配置 Claude Desktop

若要将此 MCP 服务与 Claude Desktop 搭配使用：

1. 找到 Claude Desktop 配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%/Claude/claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json

2. 将 Jira MCP 服务添加到配置中：

   {
     "mcp_servers": [
       {
         "name": "jira-server",
         "command": "npm start",
         "cwd": "/absolute/path/to/jira-server",
         "env": {
           "JIRA_HOST": "your-instance.atlassian.net",
           "JIRA_EMAIL": "[email protected]",
           "JIRA_API_TOKEN": "your-api-token",
           "JIRA_API_VERSION": "3",
           "JIRA_CUSTOM_FIELDS": "summary,description,status,priority,assignee,issuetype,parent,subtasks",
           "LOG_LEVEL": "info"
         }
       }
     ]
   }
   

   将 /absolute/path/to/jira-server 替换为克隆的仓库的绝对路径。

3. 重启 Claude Desktop 以应用更改。

可用工具

项目信息

// Get project information
{
  projectKey: "PROJECT",
  expand: ["lead", "description", "url"] // Optional
}

// List all available issue types
// No parameters required

// List all available Jira fields
// No parameters required

// List all available issue link types
// No parameters required

用户管理

// Get user's account ID by email
{
  email: "[email protected]"
}

// Add a watcher to an issue
{
  issueKey: "PROJECT-123",
  username: "[email protected]"
}

问题检索

// Get all issues in a project
{
  projectKey: "PROJECT"
}

// Get issues with JQL filtering
{
  projectKey: "PROJECT",
  jql: "status = 'In Progress' AND assignee = currentUser()"
}

// Get more issues at once (default: 50)
{
  projectKey: "PROJECT",
  maxResults: 100
}

// Get specific fields
{
  projectKey: "PROJECT",
  fields: ["summary", "status", "assignee", "labels"]
}

问题创建

// Create a standard issue
{
  projectKey: "PROJECT",
  summary: "Issue title",
  issueType: "Task",  // or "Story", "Bug", etc.
  description: "Detailed description",
  assignee: "[email protected]",
  labels: ["frontend", "urgent"],
  components: ["ui", "api"],
  priority: "High"
}

// Create a subtask
{
  projectKey: "PROJECT",
  summary: "Subtask title",
  issueType: "Subtask",
  description: "Subtask details",
  assignee: "[email protected]",
  parent: "PROJECT-123"
}

问题更新

// Update issue fields
{
  issueKey: "PROJECT-123",
  summary: "Updated title",
  description: "New description",
  assignee: "[email protected]",
  status: "In Progress",
  priority: "High", 
  labels: ["frontend", "updated"],
  components: ["ui"]
}

批量更新问题

// Update multiple issues with the same values
{
  issueKeys: ["PROJECT-123", "PROJECT-124", "PROJECT-125"],
  priority: "High",
  status: "In Progress"
}

// Add labels to multiple issues (preserves existing labels)
{
  issueKeys: ["PROJECT-123", "PROJECT-124", "PROJECT-125"],
  addLabels: ["urgent", "sprint-5"]
}

// Remove labels from multiple issues
{
  issueKeys: ["PROJECT-123", "PROJECT-124", "PROJECT-125"],
  removeLabels: ["outdated"]
}

// Replace all labels on multiple issues
{
  issueKeys: ["PROJECT-123", "PROJECT-124", "PROJECT-125"],
  setLabels: ["frontend", "sprint-6"]
}

// Add components to multiple issues
{
  issueKeys: ["PROJECT-123", "PROJECT-124", "PROJECT-125"],
  addComponents: ["api"]
}

// Complex bulk update
{
  issueKeys: ["PROJECT-123", "PROJECT-124", "PROJECT-125"],
  status: "In Progress",
  priority: "High",
  assignee: "[email protected]",
  addLabels: ["sprint-6"],
  removeLabels: ["backlog"],
  addComponents: ["api"]
}

问题链接

// Create issue link
{
  linkType: "Blocks",  // from list_link_types
  inwardIssueKey: "PROJECT-124",  // blocked issue
  outwardIssueKey: "PROJECT-123",  // blocking issue
  comment: "Blocking due to dependency" // Optional
}

问题删除

// Delete single issue
{
  issueKey: "PROJECT-123"
}

// Delete issue with subtasks
{
  issueKey: "PROJECT-123",
  deleteSubtasks: true
}

// Delete multiple issues
{
  issueKeys: ["PROJECT-123", "PROJECT-124"]
}

工作流管理

// Get available transitions
{
  issueKey: "PROJECT-123"
}

// Transition an issue by transition name
{
  issueKey: "PROJECT-123",
  transitionName: "In Progress"
}

// Transition an issue by transition ID with comment
{
  issueKey: "PROJECT-123",
  transitionId: "31",
  comment: "Moving to in progress as development has started"
}

// Transition with additional fields
{
  issueKey: "PROJECT-123",
  transitionName: "Done",
  fields: {
    "resolution": { 
      "name": "Fixed" 
    }
  }
}

问题评论

// Add a comment
{
  issueKey: "PROJECT-123",
  body: "This is a comment with **bold** and *italic* formatting"
}

// Add a comment with visibility restrictions
{
  issueKey: "PROJECT-123",
  body: "This comment is only visible to a specific role",
  visibility: {
    type: "role",
    value: "Administrators"
  }
}

文本格式

此服务支持增强的 Markdown 风格格式，可用于描述和评论：

• 段落：以空行分隔
• 列表：使用 - 或 * 表示项目符号列表，使用 1. 表示编号列表
• 标题：使用 # 语法（# Header 1、## Header 2），或使用以 : 结尾且后跟空行的行
• 文本格式：使用 **bold**、*italic* 和 `code`
• 代码块：使用三个反引号（```）表示代码块，可选指定语言

示例：

# Issue Description

This issue needs to be addressed **urgently**.

## Requirements:
- Implement the API endpoint
- Add proper error handling
- Write unit tests

Steps to reproduce:
1. Navigate to the dashboard
2. Click on the settings icon
3. Observe the error message

```javascript
// Current problematic code:
function getData() {
  return fetch('/api/data').then(res => res.json());
}
```

*Note*: This is blocking the release.

错误处理

此服务会针对以下情况提供详细的错误消息：

• 无效参数
• 身份验证问题
• 缺少必填字段
• 权限问题
• 找不到资源的错误
• API 速率限制
• 工作流验证错误

日志记录

你可以通过设置 LOG_LEVEL 环境变量来控制日志详细程度：

LOG_LEVEL=debug   # Most verbose, shows all details
LOG_LEVEL=info    # Default, shows general information
LOG_LEVEL=warn    # Shows only warnings and errors
LOG_LEVEL=error   # Shows only errors

自定义

自定义字段

若要使用自定义 Jira 字段，请将其添加到 JIRA_CUSTOM_FIELDS 环境变量中：

JIRA_CUSTOM_FIELDS=summary,description,status,priority,assignee,issuetype,parent,subtasks,customfield_10001,customfield_10002

随后即可在请求中使用这些自定义字段：

// Update with custom fields
{
  issueKey: "PROJECT-123",
  customFields: {
    "customfield_10001": "Custom value",
    "customfield_10002": { "value": "Option 1" }
  }
}

字段类型

不同的自定义字段可能需要不同的格式：

• 文本字段：简单的字符串值
• 选择/选项字段：包含 value 属性的对象
• 用户字段：包含 id 属性的对象（账户 ID）
• 多选字段：包含 value 属性的对象数组
• 日期字段：采用 ISO 格式的字符串

示例：

{
  issueKey: "PROJECT-123",
  customFields: {
    "customfield_10001": "Text value",               // Text field
    "customfield_10002": { "value": "Option 1" },    // Select field
    "customfield_10003": { "id": "123456:abcdef" },  // User field
    "customfield_10004": [                           // Multi-select field
      { "value": "Option 1" },
      { "value": "Option 2" }
    ],
    "customfield_10005": "2023-04-30"                // Date field
  }
}

开发

项目结构

jira-server/
├── src/
│   ├── index.ts             # Main server entry point
│   ├── services/            # Service modules
│   │   └── JiraService.ts   # Jira API integration
│   ├── types/               # Type definitions
│   │   └── index.ts         # Schema definitions
│   └── utils/               # Utility functions
│       └── formatters.ts    # Text formatting utilities
├── build/                   # Compiled JavaScript
├── package.json             # Project dependencies
├── tsconfig.json            # TypeScript configuration
└── .env.example             # Environment variables template

测试工具

你可以使用 MCP Inspector 直接测试服务：

npm run inspector

这将启动一个交互式会话，你可以在其中测试工具调用并查看响应。

贡献

欢迎贡献！请随时提交拉取请求。

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 进行更改
4. 运行测试和代码检查（npm run lint）
5. 提交更改（git commit -m 'Add some amazing feature'）
6. 推送到分支（git push origin feature/amazing-feature）
7. 创建拉取请求

故障排除

常见问题

1. 身份验证失败

   • 确保 JIRA_HOST、JIRA_EMAIL 和 JIRA_API_TOKEN 正确
   • 对于 Cloud 实例，请确认 API 令牌是在 https://id.atlassian.com/manage-profile/security/api-tokens 生成的

2. 权限错误

   • 确保与 API 令牌关联的用户在 Jira 中拥有适当的权限

3. 字段无效错误

   • 使用 list_fields 工具获取正确的字段 ID
   • 检查自定义字段的格式（某些字段需要对象，而不是简单值）

4. 连接问题

   • 检查与 Jira 实例的网络连接
   • 确认防火墙设置允许出站连接

5. 速率限制

   • 如果遇到速率限制，请在批量操作之间增加延迟，或减少批次大小

许可证

MIT

参考资料

• Model Context Protocol
• Jira REST API 文档
• Jira REST API 示例
• Atlassian 文档格式（ADF）
• Jira 客户端库
• Zod 模式验证