使用说明

JIRA MCP服务器

MCP（模型上下文协议）服务器，为Claude提供与JIRA交互的工具，用于冲刺管理、问题跟踪和附件处理。

安装

选项1：从npm安装

npm install -g @suppleaardvark/jira-mcp-server

选项2：从源代码构建

git clone https://github.com/suppleaardvark/jira-mcp-server.git
cd jira-mcp-server
npm install
npm run build

设置

1.获取JIRA API证书

登录您的Atlassian帐户https://id.atlassian.com
首选安全 → API令牌 → 创建API令牌
为其命名（例如“Claude MCP”）并复制令牌

2.配置环境变量

必修的：

export JIRA_BASE_URL="https://your-domain.atlassian.net"
export JIRA_EMAIL="your-email@example.com"
export JIRA_API_TOKEN="your-api-token"

可选：

# Restrict which tools are available (comma-separated scopes)
export JIRA_SCOPES="boards:read,sprints:read,issues:read"

# Restrict access to specific boards (pipe-separated, by ID or name)
export JIRA_ALLOWED_BOARDS="123|My Project Board"

# Restrict access to specific projects (pipe-separated)
export JIRA_ALLOWED_PROJECTS="PROJ|DEV"

# Restrict access to specific issue types (pipe-separated)
export JIRA_ALLOWED_ISSUE_TYPES="Bug|Task|Story"

看权限范围和资源允许列表了解详情。

3.配置MCP客户端

添加到您的MCP客户端配置中（例如，Claude Desktop claude_desktop_config.json):

如果从npm安装：

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": [
         "-y",
         "@suppleaardvark/jira-mcp-server"
      ],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

如果从源代码构建：

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

使用受限范围（只读示例）：

{
  "mcpServers": {
    "jira": {
      "command": "jira-mcp-server",
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_SCOPES": "boards:read,sprints:read,issues:read,comments:read,attachments:read"
      }
    }
  }
}

可用工具

Sprint工具

`jira_list_boards`

列出所有可访问的JIRA板。

参数： 无

退货： 董事会ID、名称、类型（scrum/bankan）和项目密钥。

`jira_get_active_sprint`

获取板的当前活动冲刺。

参数：

boardId （数字，必填）-板ID

退货： Sprint ID、名称、州、日期和目标。

`jira_list_sprints`

列出一个板或项目的冲刺，按最近的第一个排序。支持分页。

参数：

boardId （数字，可选）-电路板ID boardId 或 projectKey 是必需的。
projectKey （string，可选）-项目键，用于从项目中的所有板获取冲刺。要么 boardId 或 projectKey 是必需的。
state （字符串，可选）-按状态筛选： active, future，或 closed。如果未指定，则返回所有冲刺。
startAt （number，可选）-返回分页的第一个sprint的索引（默认值：0）
maxResults （数字，可选）-要返回的最大冲刺次数（默认值：50）

退货： 包含ID、名称、状态、日期、目标和boardId的冲刺数组。还包括分页信息(total, startAt, maxResults, hasMore).

示例-获取项目最近关闭的冲刺：

{
  "projectKey": "PROJ",
  "state": "closed",
  "maxResults": 10
}

示例-通过冲刺进行寻呼：

{
  "boardId": 123,
  "startAt": 10,
  "maxResults": 10
}

`jira_get_sprint_issues`

在冲刺中解决所有问题。

参数：

sprintId （数字，必填）-冲刺ID
maxResults （数字，可选）-要返回的最大问题数（默认值：50）
fields （string[]，可选）-要包含的字段。违约： ["key", "summary", "status", "statusCategory", "assignee", "priority"].使用 "customFields" 以包含自定义字段。

退货： 请求字段有问题。

`jira_get_my_sprint_issues`

在sprint中获取分配给当前用户的问题。

参数：

sprintId （数字，必填）-冲刺ID
maxResults （数字，可选）-要返回的最大问题数（默认值：200）
fields （string[]，可选）-要包含的字段。违约： ["key", "summary", "status", "statusCategory", "assignee", "priority"].使用 "customFields" 以包含自定义字段。

退货： 分配给您的问题，按状态和优先级排序。

问题工具

`jira_get_issue`

获取有关问题的详细信息。

参数：

issueKey （字符串，必填）-问题密钥（例如“PROJ-123”）
fields （string[]，可选）-要包含的字段。默认值：所有字段。选项： key, summary, description, type, status, statusCategory, priority, assignee, reporter, created, updated, labels, components, attachmentCount, commentCount, parent, customFields.

退货： 带有请求字段的问题详细信息。自定义字段以人类可读的名称返回。

`jira_search_issues`

使用JQL搜索问题。

参数：

jql （string，必填）-JQL查询字符串
maxResults （数字，可选）-最大结果（默认值：50）
fields （string[]，可选）-要包含的字段。违约： ["key", "summary", "status", "statusCategory", "assignee", "type", "parent"].使用 "customFields" 以包含自定义字段。

退货： 请求字段有问题。还包括 hasMore 指示除此之外是否存在其他结果的标志 maxResults.

重要提示： 查询必须与项目筛选器或其他限制（例如受让人、sprint）绑定。无边界查询，如 status = "Open" 被JIRA的API拒绝。

JQL查询示例：

project = PROJ AND status = "In Progress"
assignee = currentUser() AND sprint in openSprints()
project = PROJ AND labels = bug AND created >= -7d

`jira_get_backlog_stats`

获取与JQL查询匹配的问题的聚合统计信息，而无需获取所有问题详细信息。

参数：

jql （string，必填）-JQL查询字符串（例如，“项目=PROJ”）
boardId （数字，可选）-按板ID筛选（根据板的项目添加项目筛选器）
excludeResolved （布尔值，可选）-排除已解决的问题（添加“解决方案为空”）
issueTypes （string[]，可选）-按问题类型筛选（例如，[“Bug”，“Story”]）
assignees （string[]，可选）-按指派者筛选（未指派的问题使用“未指派”）
sprint （数字，可选）-按冲刺ID筛选
groupBy （string[]，可选）-分组依据的字段。选项： status, type, priority, assignee, reporter, labels, components, resolution, project。如果指定，则替换默认聚合。
pivot （对象，可选）-自定义数据透视表配置：
- rowField （字符串，必填）-枢轴行字段
- columnField （字符串，必填）-枢轴列字段
- action （字符串，可选）-聚合： count （默认）， sum, avg, cardinality
- valueField （字符串，可选）-sum/avg的字段ID（例如。， customfield_10024 故事要点）
fieldFilters （object[]，可选）-通过JQL应用的其他基于字段的过滤器

退货： 按状态、类型、优先级、受让人和 byTypeAndStatus 枢轴表。当 pivot 指定，包括具有行/列总计的自定义数据透视结果。分析多达4000个问题。

示例-受让人的故事点：

{
  "jql": "project = ED",
  "sprint": 616,
  "pivot": {
    "rowField": "assignee",
    "columnField": "status",
    "action": "sum",
    "valueField": "customfield_10024"
  }
}

`jira_get_sprint_report`

生成一份用于回顾的冲刺报告。返回按状态类别、错误指标和标签特定跟踪分组的问题计数和故事点。

参数：

sprintId （数字，必填）-当前冲刺ID
projectKey （字符串，必填）-项目密钥（例如“PROJ”）
storyPointsField （字符串，必填）-故事点的自定义字段ID（使用 jira_get_field_schema 找到这个）
previousSprintId （数字，可选）-用于比较的上一个冲刺ID
labelsOfInterest （string[]，可选）-单独跟踪的标签（例如。， ["NZ", "TopTen"])
statusGroups （对象，可选）-自定义状态分组。键是组名，值是状态名数组。
includeTriage （布尔值，可选）-包括分类指标（sprint开始后创建的问题）。默认值：false。
includeInflow （布尔值，可选）-包括流入指标（sprint开始后从积压中提取的问题）。需要更改日志查找。默认值：false。

退货：

statusGroups -每个状态组的问题计数和故事点（待办事项、已阻止、进行中、设计审查、待测试、已完成）
triage -（如果 includeTriage)冲刺开始后创建的问题（冲刺中期添加的新项目）
inflow -（如果 includeInflow)sprint开始后，从积压中删除了预先存在的问题
bugs.backlogTotal -所有sprint中都没有bug
bugs.fixedInSprint -处于完成/准备测试状态的错误
bugs.notFixedInSprint -其他状态下的Bug
labels -对于每个感兴趣的标签：完整与不完整计数

例子：

{
  "sprintId": 616,
  "previousSprintId": 615,
  "projectKey": "ED",
  "storyPointsField": "customfield_10024",
  "labelsOfInterest": ["NZ", "TopTen"]
}

`jira_get_issue_comments`

获取对某个问题的评论。

参数：

issueKey （字符串，必填）-问题密钥
maxResults （数字，可选）-最大评论数（默认值：20）

退货： 带有作者、正文和创作日期的评论。

`jira_create_issue`

创建新的JIRA问题。

参数：

projectKey （字符串，必填）-项目密钥（例如“PROJ”）
summary （字符串，必填）-发行标题
issueType （字符串，必填）-类型（例如，“任务”、“Bug”、“故事”、“史诗”、“子任务”）
description （字符串，可选）-问题描述
priority （字符串，可选）-优先级名称（例如，“高”、“中”、“低”）
labels （string[]，可选）-要添加的标签
assignee （字符串，可选）-Atlassian帐户ID
parent （字符串，可选）-父问题密钥（用于子任务或史诗链接）
components （string[]，可选）-组件名称

退货： 已创建问题密钥、ID和URL。

`jira_update_issue`

更新现有问题的字段。

参数：

issueKey （字符串，必填）-问题密钥
summary （字符串，可选）-新摘要
description （字符串，可选）-新描述
assignee （字符串，可选）-Atlassian帐户ID（空表示取消分配）
priority （字符串，可选）-优先级名称
labels （string[]，可选）-要设置的标签
customFields （对象，可选）-要更新的自定义字段。键是字段ID（例如“customfield_10001”），值取决于字段类型。

`jira_get_transitions`

获取问题的可用状态转换。

参数：

issueKey （字符串，必填）-问题密钥

退货： 具有ID、名称和目标状态的可用转换。

`jira_transition_issue`

将问题移动到新状态。

参数：

issueKey （字符串，必填）-问题密钥
transitionId （字符串，必填）-转换ID（来自 jira_get_transitions)
comment （字符串，可选）-要与转换一起添加的注释

`jira_add_comment`

为问题添加评论。

参数：

issueKey （字符串，必填）-问题密钥
body （字符串，必填）-注释文本

`jira_get_issue_history`

获取显示所有字段更改的问题的更改日志/历史记录。

参数：

issueKey （字符串，必填）-问题密钥
maxResults （数字，可选）-最大历史条目数（默认值：100）

退货： 包含作者、时间戳和字段更改（从/到值）的历史条目。

`jira_get_field_schema`

获取可用的JIRA字段及其ID、名称和类型。有助于发现自定义字段ID（例如，查找用于统计数据聚合的“故事点”的ID）。

参数：

projectKey （字符串，可选）-如果提供，则仅返回为此项目配置的字段。这显示了实际使用的字段，而不仅仅是JIRA中的所有字段。
customOnly （boolean，可选）-如果为true，则仅返回自定义字段
searchTerm （字符串，可选）-按名称或ID筛选字段（不区分大小写）

退货： 字段元数据，包括ID、名称、是否为自定义和模式类型。

示例-查找项目的故事点字段：

{
  "projectKey": "ED",
  "searchTerm": "story"
}

`jira_list_field_values`

列出JIRA字段的离散值。有助于在创建/更新问题之前发现有效值。

参数：

field （string，必填）-列出值的字段。选项： labels, priorities, statuses, issueTypes, resolutions, components
projectKey （字符串，可选）-项目密钥（必需 components 现场）
searchTerm （字符串，可选）-按名称筛选值（不区分大小写的部分匹配）
maxResults （数字，可选）-要返回的最大值（默认值：标签为1000）

退货： 字段值数组 id （如适用）， name，可选 description，并针对特定领域 extra 数据（例如，状态类别、图标URL）。

示例-列出所有标签：

{
  "field": "labels"
}

示例-列出项目的组件：

{
  "field": "components",
  "projectKey": "PROJ"
}

示例-搜索状态：

{
  "field": "statuses",
  "searchTerm": "progress"
}

`jira_debug_search`

用于探索原始JIRA数据的调试工具。返回原始字段数据和字段名映射。

参数：

jql （string，必填）-JQL查询字符串
maxResults （数字，可选）-要返回的最大问题数（默认值：1）
fields （string[]，可选）-要返回的特定JIRA字段ID

退货： 包含字段值和字段ID到名称的映射的原始问题数据。

随机工具

`jira_list_attachments`

列出问题的所有附件。

参数：

issueKey （字符串，必填）-问题密钥

退货： 附件ID、文件名、大小、MIME类型和作者。

`jira_download_attachment`

将附件下载到本地文件。

参数：

attachmentId （字符串，必填）-附件ID（来自 jira_list_attachments)
outputPath （字符串，必填）-保存附件的本地文件路径

`jira_upload_attachment`

将文件作为问题的附件上传。

参数：

issueKey （字符串，必填）-问题密钥（例如“PROJ-123”）
filePath （字符串，必填）-要上传的本地文件路径

退货： 上传的附件详细信息，包括ID、文件名、大小和MIME类型。

权限范围

使用 JIRA_SCOPES 环境变量，用于限制可用的工具。这对于限制共享环境中的访问或强制最低权限访问非常有用。

配置范围之外的工具对代理完全隐藏——它们不会出现在工具列表中，代理也不会知道它们的存在。

默认行为： 如果 JIRA_SCOPES 未设置或为空，除选择加入范围外，所有工具都已启用，如 debug.

可用范围

范围	工具
`boards:read`	`jira_list_boards`
`sprints:read`	`jira_get_active_sprint`, `jira_list_sprints`, `jira_get_sprint_issues`, `jira_get_my_sprint_issues`, `jira_get_sprint_report`
`issues:read`	`jira_get_issue`, `jira_search_issues`, `jira_get_transitions`, `jira_get_issue_history`, `jira_get_backlog_stats`, `jira_get_field_schema`, `jira_list_field_values`
`issues:write`	`jira_create_issue`, `jira_update_issue`, `jira_transition_issue`
`comments:read`	`jira_get_issue_comments`
`comments:write`	`jira_add_comment`
`attachments:read`	`jira_list_attachments`, `jira_download_attachment`
`attachments:write`	`jira_upload_attachment`
`debug`	`jira_debug_search` （选择加入，默认不包括在内）

例子

只读访问：

JIRA_SCOPES="boards:read,sprints:read,issues:read,comments:read,attachments:read"

仅限问题（读写）：

JIRA_SCOPES="issues:read,issues:write"

完全访问（显式）：

JIRA_SCOPES="boards:read,sprints:read,issues:read,issues:write,comments:read,comments:write,attachments:read,attachments:write"

无效的作用域名称被记录为警告并被忽略。

资源允许列表

除了工具级范围外，您还可以使用allowlists限制对特定板、项目和问题类型的访问。allowlist之外的资源对代理隐藏。

董事会允许名单

使用 JIRA_ALLOWED_BOARDS 限制代理可以访问哪些板（及其冲刺）。

# By board ID
JIRA_ALLOWED_BOARDS="123|456"

# By board name (case-insensitive)
JIRA_ALLOWED_BOARDS="Project Alpha|Project Beta"

# Mix of IDs and names
JIRA_ALLOWED_BOARDS="123|Project Beta"

行为：

jira_list_boards 只允许归还木板
jira_get_active_sprint 不允许的电路板故障
jira_get_sprint_issues 和 jira_get_my_sprint_issues 在不允许的板上冲刺失败
如果未设置，所有板都可以访问

问题类型允许列表

使用 JIRA_ALLOWED_ISSUE_TYPES 限制代理可以访问哪些问题类型。

# Allow only bugs and tasks
JIRA_ALLOWED_ISSUE_TYPES="Bug|Task"

# Allow common work items (case-insensitive)
JIRA_ALLOWED_ISSUE_TYPES="bug|task|story|sub-task"

行为：

jira_get_issue 因不允许的类型问题而失败
jira_search_issues 过滤掉不允许类型的问题
jira_create_issue 尝试创建不允许的类型时失败
对于不允许的类型，所有问题操作（更新、转换、注释、附件）都失败
如果未设置，则可以访问所有问题类型

项目许可清单

使用 JIRA_ALLOWED_PROJECTS 限制代理可以访问哪些项目。这将按项目密钥筛选问题。

# Allow only specific projects
JIRA_ALLOWED_PROJECTS="PROJ|DEV"

# Single project (case-insensitive)
JIRA_ALLOWED_PROJECTS="proj"

行为：

jira_get_issue 因不允许的项目问题而失败
jira_search_issues 从不允许的项目中过滤出问题
jira_create_issue 尝试在不允许的项目中创建问题时失败
对于不允许的项目，所有问题操作（更新、转换、注释、附件）都失败
如果未设置，则所有项目都可以访问

组合示例

限制代理只能查看特定项目中的错误和任务：

{
  "mcpServers": {
    "jira": {
      "command": "jira-mcp-server",
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_SCOPES": "boards:read,sprints:read,issues:read",
        "JIRA_ALLOWED_BOARDS": "Project Alpha",
        "JIRA_ALLOWED_PROJECTS": "PROJ",
        "JIRA_ALLOWED_ISSUE_TYPES": "Bug|Task"
      }
    }
  }
}

示例用法

User: What's in my current sprint?

Claude: [Uses jira_list_boards to find boards]
Claude: [Uses jira_get_active_sprint with boardId]
Claude: [Uses jira_get_sprint_issues with sprintId]

Here are the issues in your current sprint:
- PROJ-101: Implement login page (In Progress, assigned to Alice)
- PROJ-102: Fix checkout bug (To Do, unassigned)
...

User: Create a bug for the login timeout issue

Claude: [Uses jira_create_issue]

Created PROJ-103: Login timeout after 5 minutes of inactivity

API权限

API令牌需要对以下内容进行读取访问：

董事会和疾跑（敏捷API）
问题和评论
附件

对于写入操作，请确保令牌的关联帐户具有以下权限：

在目标项目中创建/编辑问题
添加评论
过渡问题

故障排除

“缺少JIRA配置”错误

确保设置了所有三个环境变量： JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN

“401未经授权”错误

验证您的API令牌是否正确且尚未过期
确认您的电子邮件与Atlassian帐户匹配

“404 Not Found”用于板/冲刺

Board/sprint API要求项目使用Scrum或看板
没有板的经典项目不会有冲刺数据

创建/更新时“403禁止”

检查您的帐户是否具有必要的项目权限

使用说明

JIRA MCP服务器

安装

选项1：从npm安装

选项2：从源代码构建

设置

1.获取JIRA API证书

2.配置环境变量

3.配置MCP客户端

可用工具

Sprint工具

jira_list_boards

jira_get_active_sprint

jira_list_sprints

jira_get_sprint_issues

jira_get_my_sprint_issues

问题工具

jira_get_issue

jira_search_issues

jira_get_backlog_stats

jira_get_sprint_report

jira_get_issue_comments

jira_create_issue

jira_update_issue

jira_get_transitions

jira_transition_issue

jira_add_comment

jira_get_issue_history

jira_get_field_schema

jira_list_field_values

jira_debug_search

随机工具

jira_list_attachments

jira_download_attachment

jira_upload_attachment

权限范围

可用范围

例子

资源允许列表

董事会允许名单

问题类型允许列表

项目许可清单

组合示例

示例用法

API权限

故障排除

相关 MCP

Jira集成服务

GitHub仓库分析工具

Gitee API管理工具

Jira API集成工具

Linear问题跟踪集成服务

Redmine MCP服务器

`jira_list_boards`

`jira_get_active_sprint`

`jira_list_sprints`

`jira_get_sprint_issues`

`jira_get_my_sprint_issues`

`jira_get_issue`

`jira_search_issues`

`jira_get_backlog_stats`

`jira_get_sprint_report`

`jira_get_issue_comments`

`jira_create_issue`

`jira_update_issue`

`jira_get_transitions`

`jira_transition_issue`

`jira_add_comment`

`jira_get_issue_history`

`jira_get_field_schema`

`jira_list_field_values`

`jira_debug_search`

`jira_list_attachments`

`jira_download_attachment`

`jira_upload_attachment`