Skip to main content
Glama
deenesjakoruzh
r-kitaev

mcp-jira-server

by r-kitaev
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

用于 Claude Code 的 MCP Jira 服务器

一个用于 Claude Code 集成的全面模型上下文协议 (MCP) 服务器。该服务器提供完整的 Jira 功能，包括问题管理、冲刺操作、评论、附件和批量处理。

License: MIT TypeScript Node.js

⚠️ 安全提示：切勿提交您的 API 令牌！请使用环境变量（例如在 ~/.zshrc 中）或密钥管理工具。

🚀 功能

📋 问题管理 (12 个工具)

  • create-issue - 创建问题，全面支持包括自定义字段和日期在内的所有字段

  • update-issue - 使用智能字段处理更新现有问题

  • get-issue - 获取详细的问题信息

  • search-issues - 使用 JQL 或简化的过滤器进行高级搜索，并支持日期

  • transition-issue - 在工作流状态之间移动问题

  • link-issues - 创建问题之间的关系（具有智能类型匹配）

  • get-link-types - 列出可用的问题链接类型

  • get-fields - 显示项目/问题类型的可用字段

  • diagnose-fields - 排除字段配置故障并查找自定义字段 ID

  • create-epic-with-subtasks - 一次性创建带有多个子任务的史诗 (Epic)

  • create-task-for-epic - 创建链接到史诗的任务（针对本地化 Jira 进行了优化）

💬 评论与历史记录 (3 个工具)

  • get-comments - 读取带有作者和时间戳信息的问题评论

  • get-history - 查看带有字段修改的详细变更历史

  • add-comment - 添加支持 Atlassian 文档格式的评论

  • batch-comment - 同时向多个问题添加相同的评论

📎 附件 (2 个工具)

  • get-attachments - 列出带有元数据（大小、类型、上传日期）的附件

  • upload-attachment - 使用 base64 编码上传文件

🏃 冲刺与敏捷管理 (4 个工具)

  • get-boards - 列出敏捷项目的可用 Jira 看板

  • get-sprints - 查看带有状态指示器的看板冲刺

  • move-issue-to-sprint - 在冲刺和待办事项之间移动问题

  • create-sprint - 创建带有可选开始/结束日期的新冲刺

资源

  • jira://projects - 列出所有可访问的项目

  • jira://project/{key} - 获取特定项目详情

  • jira://issue/{key} - 获取特定问题详情

  • jira://myself - 当前用户信息

  • jira://search?jql={query} - 搜索结果

提示词 (Prompts)

  • standup-report - 生成每日站会报告

  • sprint-planning - 协助冲刺规划活动

  • bug-triage - 帮助优先处理和分类 Bug

  • release-notes - 从已完成的问题生成发行说明

  • epic-status - 全面的史诗进度报告

安装

  1. 克隆仓库：

git clone https://github.com/tom28881/JIRA_MCP.git
cd JIRA_MCP

  1. 安装依赖：

npm install

  1. 构建项目：

npm run build

  1. 在环境变量中配置您的 Jira 凭据（例如 ~/.zshrc）：

对于 Jira Cloud：

export JIRA_HOST=https://your-company.atlassian.net
export JIRA_EMAIL=your-email@company.com
export JIRA_API_TOKEN=your-api-token

对于 Jira Server/DC 9.12+：

export JIRA_HOST=https://jira.your-company.com
export JIRA_PAT=your-personal-access-token

对于 Jira Server/DC (旧版)：

export JIRA_HOST=https://jira.your-company.com
export JIRA_USERNAME=your-username
export JIRA_PASSWORD=your-password

请参阅 docs/AUTH_SETUP.md 获取完整的身份验证指南。

获取凭据

Jira Cloud (API 令牌)

  1. 登录 Atlassian 账户设置

  2. 点击“创建 API 令牌”

  3. 给它起个名字（例如“MCP Server”）

  4. 复制令牌并将其作为 JIRA_API_TOKEN 添加到您的 shell 配置中（例如 ~/.zshrc）

Jira Server/DC 9.12+ (个人访问令牌)

  1. 登录 Jira Server/DC

  2. 转到 个人资料 → 个人访问令牌

  3. 点击 创建令牌

  4. 设置名称和过期时间（最长 365 天）

  5. 立即复制令牌 — 之后无法再次查看

  6. 将其作为 JIRA_PAT 添加到您的 shell 配置中（例如 ~/.zshrc）

请参阅 docs/AUTH_SETUP.md 获取详细的设置说明。

Claude Code 配置

要将此 MCP 服务器与 Claude Code 一起使用，您需要在 MCP 设置中进行配置。

选项 1：使用环境变量（推荐）

在您的 shell 配置（例如 ~/.zshrc）中设置带有环境变量的服务器：

# Add to ~/.zshrc
export JIRA_HOST="https://your-company.atlassian.net"
export JIRA_EMAIL="your-email@company.com"
export JIRA_API_TOKEN="your-api-token"
export JIRA_DEFAULT_PROJECT="PROJ"

# Restart terminal or run: source ~/.zshrc
# Then run Claude Code with the MCP server
claude --mcp "node /absolute/path/to/mcp-jira-server/dist/index.js"

选项 2：添加到 Claude Code 设置

将服务器添加到您的 Claude Code 设置文件 (~/.claude/settings.json)：

{
  "mcpServers": [
    {
      "name": "jira",
      "command": "node",
      "args": ["/absolute/path/to/mcp-jira-server/dist/index.js"],
      "env": {
        "JIRA_HOST": "https://your-company.atlassian.net",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_DEFAULT_PROJECT": "PROJ"
      }
    }
  ]
}

使用示例

创建问题

Create a new bug in project PROJ with high priority about login issues
Create a story "Implement user authentication" with 5 story points and assign it to john@example.com

设置日期和时间估算

Create task "Database backup" with dueDate "next week" and originalEstimate "4h"
Update PROJ-123 with startDate "tomorrow" and dueDate "+14d"
Create issue "Quarterly review" with dueDate "31.3.2025" and originalEstimate "2 days"

创建带有子任务的史诗

Create an epic "Database Migration" in project PROJ with subtasks "Backup current data" and "Migrate schema"

创建子任务

Create a subtask "Review code" for parent issue PROJ-123

捷克语 Jira 支持

Create issue type "Úkol" in project PROJ
Create task for epic PPC-48 with summary "Database backup"

搜索问题

Find all open bugs assigned to me
Search for issues in project PROJ with label "urgent" that are not done

基于日期的搜索

Search issues due before "next week" in project PROJ
Find issues created after "2024-12-01" and updated after "yesterday"
Search for overdue issues: dueBefore "today" and status != "Done"

管理问题

Update PROJ-123 to add story points 8
Transition PROJ-456 to "In Progress"
Link PROJ-123 to PROJ-456 as "blocks"

注意：史诗-故事关系使用 epicLink 字段，而不是常规的问题链接：

Update PROJ-456 with epicLink "PROJ-100"  # Links story to epic

使用提示词

Generate a standup report for john@example.com
Help me plan the sprint for project PROJ
Create release notes for version 2.0 in project PROJ

高级配置

自定义字段

该服务器可以与任何 Jira 配置配合使用：

选项 1：自动检测（推荐）

在环境配置中保持自定义字段 ID 未设置，服务器将根据字段名称自动检测它们。

选项 2：手动配置

如果自动检测不起作用，请在您的环境中配置自定义字段 ID（例如 ~/.zshrc）：

export JIRA_FIELD_STORY_POINTS=customfield_10001
export JIRA_FIELD_ACCEPTANCE_CRITERIA=customfield_10002
export JIRA_FIELD_EPIC_LINK=customfield_10003

查找字段 ID

使用 diagnose-fields 工具查找您的 Jira 实例的正确字段 ID：

diagnose-fields project:"PROJ" issueType:"Story"

自动创建测试工单

启用故事的自动测试工单创建：

AUTO_CREATE_TEST_TICKETS=true

开发

在开发模式下运行

npm run dev

类型检查

npm run typecheck

Linting

npm run lint

功能

🌍 本地化支持

  • 自动支持本地化的 Jira 实例（捷克语、英语等）

  • 问题类型名称可以是任何语言（例如“Task”、“Úkol”、“Aufgabe”）

  • 优先级名称支持本地化（例如“High”、“Vysoká”、“Hoch”）

  • 对捷克语 Jira 配置的特殊支持

  • 适用于任何 Jira 语言设置

📅 日期和时间管理

  • 灵活的日期输入格式：

    • ISO: "2024-12-31"

    • 欧洲格式: "31.12.2024" 或 "31/12/2024"

    • 相对日期: "today", "tomorrow", "next week", "+7d", "+2w", "+1m"

    • 捷克语: "dnes", "zítra", "příští týden"

  • 时间跟踪支持：

    • 估算: "2h", "1d 4h", "3 days", "2 hodiny"

    • 自动格式转换

  • 基于日期的搜索和过滤

🔄 自动重试

服务器会自动以指数退避方式重试失败的请求（最多 3 次尝试）。

📦 强大的错误处理

  • Jira 转换的空响应处理

  • 带有上下文的详细错误消息

  • 针对缺失功能的优雅降级

📝 全面的日志记录

启用调试日志以查看详细信息：

DEBUG=* claude --mcp "./run.sh"
# or specific to jira-mcp:
DEBUG=jira-mcp claude --mcp "./run.sh"

🔒 连接测试

服务器在启动时测试连接，如果身份验证失败，则提供清晰的错误消息。

📄 Atlassian 文档格式

自动将纯文本和 Markdown 转换为 Jira 的 ADF 格式，用于富文本字段。

故障排除

使用不同的 Jira 配置

此 MCP 服务器旨在与任何 Jira 实例配合使用，无论其：

  • 语言设置（英语、捷克语、德语等）

  • 自定义字段配置

  • 项目特定设置

最佳实践：

  1. 使用 get-fields 查看您语言中的可用问题类型

  2. 使用 diagnose-fields 查找自定义字段 ID

  3. 使用来自您 Jira 的确切问题类型名称创建问题

常见问题

  1. 身份验证失败

    • 验证您的 API 令牌是否正确

    • 确保您的电子邮件与您的 Atlassian 账户匹配

    • 检查您的 Jira 实例 URL 是否包含 https://

  2. 找不到项目

    • 验证您是否有权访问该项目

    • 检查项目键是否正确（区分大小写）

  3. 自定义字段不起作用

    • 使用 diagnose-fields 工具查找项目的正确字段 ID

    • 使用 get-fields 工具查看所有可用字段

    • 自定义字段 ID 通常以 customfield_ 开头

    • 某些字段可能不适用于某些问题类型（例如史诗上的标签）

    • 史诗链接字段 ID 在不同的 Jira 实例之间有所不同

  4. 找不到链接类型

    • 使用 get-link-types 工具查看可用的链接类型

    • 链接类型在 Jira API 中区分大小写

    • 服务器将尝试进行不区分大小写的匹配

    • 史诗-故事关系使用 epicLink 字段，而不是常规的问题链接

  5. 史诗-故事链接问题

    • 为项目和“Story”问题类型运行 diagnose-fields

    • 在环境配置中更新 JIRA_FIELD_EPIC_LINK 为正确的字段 ID

    • 更新后重启终端或运行 source ~/.zshrc

调试模式

设置 DEBUG 环境变量以获取详细日志：

DEBUG=* claude --mcp "./run.sh"
# or
DEBUG=jira-mcp claude --mcp "./run.sh"

查看日志

日志输出到 stderr，包括：

  • 连接状态

  • API 请求和响应

  • 带有上下文的错误详情

  • 性能指标

贡献

请参阅 CONTRIBUTING.md 获取开发指南。

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件

支持

对于问题和功能请求，请使用 GitHub 问题跟踪器。

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Resources

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/r-kitaev/mcp-jira-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server