MCP 服务器

Jira MCP Server

一个兼容 Jira V2 和 V3 API 以及自定义字段的 MCP 服务器

fkesheh

开发者工具

访问服务器

README

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 助手

安装

克隆此存储库：

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

安装依赖项：
```
npm install
```
设置环境变量：
```
cp .env.example .env
```

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

JIRA_HOST=your-instance.atlassian.net
JIRA_EMAIL=your-email@example.com
JIRA_API_TOKEN=your-api-token

构建服务器：
```
npm run build
```

用法

启动服务器

npm start

开发模式

对于具有自动重新加载功能的开发：

npm run dev

Linting 和格式化

# 运行 ESLint
npm run lint

# 使用 Prettier 格式化代码
npm run format

配置 Claude Desktop

要将此 MCP 服务器与 Claude Desktop 一起使用：

找到您的 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

将 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": "your-email@example.com",
        "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 替换为您克隆的存储库的绝对路径。

重新启动 Claude Desktop 以应用更改。

可用工具

项目信息

// 获取项目信息
{
  projectKey: "PROJECT",
  expand: ["lead", "description", "url"] // 可选
}

// 列出所有可用的问题类型
// 无需参数

// 列出所有可用的 Jira 字段
// 无需参数

// 列出所有可用的问题链接类型
// 无需参数

用户管理

// 通过电子邮件获取用户的帐户 ID
{
  email: "user@example.com"
}

// 向问题添加观察者
{
  issueKey: "PROJECT-123",
  username: "user@example.com"
}

问题检索

// 获取项目中的所有问题
{
  projectKey: "PROJECT"
}

// 使用 JQL 过滤获取问题
{
  projectKey: "PROJECT",
  jql: "status = 'In Progress' AND assignee = currentUser()"
}

// 一次获取更多问题（默认：50）
{
  projectKey: "PROJECT",
  maxResults: 100
}

// 获取特定字段
{
  projectKey: "PROJECT",
  fields: ["summary", "status", "assignee", "labels"]
}

问题创建

// 创建标准问题
{
  projectKey: "PROJECT",
  summary: "Issue title",
  issueType: "Task",  // 或 "Story", "Bug" 等
  description: "Detailed description",
  assignee: "user@example.com",
  labels: ["frontend", "urgent"],
  components: ["ui", "api"],
  priority: "High"
}

// 创建子任务
{
  projectKey: "PROJECT",
  summary: "Subtask title",
  issueType: "Subtask",
  description: "Subtask details",
  assignee: "user@example.com",
  parent: "PROJECT-123"
}

问题更新

// 更新问题字段
{
  issueKey: "PROJECT-123",
  summary: "Updated title",
  description: "New description",
  assignee: "user@example.com",
  status: "In Progress",
  priority: "High",
  labels: ["frontend", "updated"],
  components: ["ui"]
}

批量问题更新

// 使用相同的值更新多个问题
{
  issueKeys: ["PROJECT-123", "PROJECT-124", "PROJECT-125"],
  priority: "High",
  status: "In Progress"
}

// 将标签添加到多个问题（保留现有标签）
{
  issueKeys: ["PROJECT-123", "PROJECT-124", "PROJECT-125"],
  addLabels: ["urgent", "sprint-5"]
}

// 从多个问题中删除标签
{
  issueKeys: ["PROJECT-123", "PROJECT-124", "PROJECT-125"],
  removeLabels: ["outdated"]
}

// 替换多个问题上的所有标签
{
  issueKeys: ["PROJECT-123", "PROJECT-124", "PROJECT-125"],
  setLabels: ["frontend", "sprint-6"]
}

// 将组件添加到多个问题
{
  issueKeys: ["PROJECT-123", "PROJECT-124", "PROJECT-125"],
  addComponents: ["api"]
}

// 复杂批量更新
{
  issueKeys: ["PROJECT-123", "PROJECT-124", "PROJECT-125"],
  status: "In Progress",
  priority: "High",
  assignee: "developer@example.com",
  addLabels: ["sprint-6"],
  removeLabels: ["backlog"],
  addComponents: ["api"]
}

问题链接

// 创建问题链接
{
  linkType: "Blocks",  // 来自 list_link_types
  inwardIssueKey: "PROJECT-124",  // 被阻止的问题
  outwardIssueKey: "PROJECT-123",  // 阻止问题
  comment: "Blocking due to dependency" // 可选
}

问题删除

// 删除单个问题
{
  issueKey: "PROJECT-123"
}

// 删除带有子任务的问题
{
  issueKey: "PROJECT-123",
  deleteSubtasks: true
}

// 删除多个问题
{
  issueKeys: ["PROJECT-123", "PROJECT-124"]
}

工作流程管理

// 获取可用的转换
{
  issueKey: "PROJECT-123"
}

// 通过转换名称转换问题
{
  issueKey: "PROJECT-123",
  transitionName: "In Progress"
}

// 通过带有注释的转换 ID 转换问题
{
  issueKey: "PROJECT-123",
  transitionId: "31",
  comment: "Moving to in progress as development has started"
}

// 使用其他字段进行转换
{
  issueKey: "PROJECT-123",
  transitionName: "Done",
  fields: {
    "resolution": {
      "name": "Fixed"
    }
  }
}

问题评论

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

// 添加具有可见性限制的评论
{
  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   # 最详细，显示所有详细信息
LOG_LEVEL=info    # 默认，显示一般信息
LOG_LEVEL=warn    # 仅显示警告和错误
LOG_LEVEL=error   # 仅显示错误

自定义

自定义字段

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

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

然后，您可以在请求中使用这些自定义字段：

// 使用自定义字段更新
{
  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",               // 文本字段
    "customfield_10002": { "value": "Option 1" },    // 选择字段
    "customfield_10003": { "id": "123456:abcdef" },  // 用户字段
    "customfield_10004": [                           // 多选字段
      { "value": "Option 1" },
      { "value": "Option 2" }
    ],
    "customfield_10005": "2023-04-30"                // 日期字段
  }
}

开发

项目结构

jira-server/
├── src/
│   ├── index.ts             # 主服务器入口点
│   ├── services/            # 服务模块
│   │   └── JiraService.ts   # Jira API 集成
│   ├── types/               # 类型定义
│   │   └── index.ts         # 模式定义
│   └── utils/               # 实用程序函数
│       └── formatters.ts    # 文本格式化实用程序
├── build/                   # 编译的 JavaScript
├── package.json             # 项目依赖项
├── tsconfig.json            # TypeScript 配置
└── .env.example             # 环境变量模板

测试工具

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

npm run inspector

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

贡献

欢迎贡献！请随时提交 Pull Request。

Fork 存储库
创建您的功能分支 (git checkout -b feature/amazing-feature)
进行更改
运行测试和 linting (npm run lint)
提交您的更改 (git commit -m 'Add some amazing feature')
推送到分支 (git push origin feature/amazing-feature)
打开 Pull Request

故障排除

常见问题

身份验证失败
- 确保您的 JIRA_HOST、JIRA_EMAIL 和 JIRA_API_TOKEN 正确
- 对于 Cloud 实例，请验证 API 令牌是否在 https://id.atlassian.com/manage-profile/security/api-tokens 生成
权限错误
- 确保与 API 令牌关联的用户在 Jira 中具有适当的权限
无效字段错误
- 使用 list_fields 工具获取正确的字段 ID
- 检查自定义字段的格式（有些需要对象而不是简单值）
连接问题
- 检查与 Jira 实例的网络连接
- 验证防火墙设置是否允许出站连接
速率限制
- 如果遇到速率限制，请在批量操作之间添加延迟或减少批量大小

许可证

MIT