Jira MCP

Jira MCP

一个基于多年真实软件开发经验打造、具有鲜明理念的 Jira MCP 服务。

与通用 Jira 集成不同，这个 MCP 服务源自工程师和自动化 QC 团队的日常工作流。你会发现专为实际开发需求设计的高级工具，例如获取与某个 issue 关联的所有拉取请求、管理复杂的冲刺流转，或在整个工作流中跟踪开发信息。

它不只是另一个 API 封装，而是对专业人士实际使用 Jira 方式的真实呈现：管理冲刺、跟踪开发工作、协调发布，并让团队保持信息透明。每个工具都旨在解决现代软件开发中遇到的实际问题。

可用工具

Issue 管理

• jira_get_issue - 获取特定 issue 的详细信息，包括状态、经办人、描述、子任务和可用的流转
• jira_create_issue - 创建包含指定详细信息的新 issue（返回 key、ID 和 URL）
• jira_create_child_issue - 创建与父 issue 关联的子 issue（子任务）
• jira_update_issue - 修改现有 issue 的详细信息（支持部分更新）
• jira_list_issue_types - 列出项目中所有可用的 issue 类型及其 ID、名称和描述

搜索

• jira_search_issue - 使用 JQL（Jira 查询语言）搜索 issue，并可自定义字段和扩展选项

冲刺管理

• jira_list_sprints - 列出指定看板或项目的所有进行中和未来冲刺
• jira_get_sprint - 根据 ID 获取特定冲刺的详细信息
• jira_get_active_sprint - 获取指定看板或项目当前进行中的冲刺
• jira_search_sprint_by_name - 按名称搜索冲刺，支持精确或部分匹配

状态与流转

• jira_list_statuses - 获取项目中所有可用的 issue 状态 ID 及其名称
• jira_transition_issue - 使用有效的流转 ID，让 issue 按工作流进行流转

评论

• jira_add_comment - 为 issue 添加评论（使用 Atlassian 文档格式）
• jira_get_comments - 获取 issue 的所有评论

工时记录

• jira_add_worklog - 添加工时记录，以跟踪 issue 上花费的时间

历史与审计

• jira_get_issue_history - 获取 issue 的完整变更历史

Issue 关联关系

• jira_get_related_issues - 获取具有关联关系的 issue（阻塞、被阻塞、相关等）
• jira_link_issues - 在两个 issue 之间创建链接并定义其关联关系

版本管理

• jira_get_version - 获取特定项目版本的详细信息
• jira_list_project_versions - 列出项目中的所有版本及其详细信息

开发信息

• jira_get_development_information - 通过开发工具集成（GitHub、GitLab、Bitbucket）获取与 issue 关联的分支、拉取请求和提交

安装

将此提示词复制到你的 AI 助手中：

Install the Jira MCP server (https://github.com/nguyenvanduocit/jira-mcp) for my Claude Desktop or Cursor IDE. Read the MCP documentation carefully and guide me through the installation step by step.

如果你的 AI 助手无法帮助你完成此安装，则说明配置有误或 AI 工具不够有效。称职的 AI 助手应该能够指导你安装 MCP。

CLI 用法

除了 MCP 服务之外，jira-mcp 还提供独立的 CLI 二进制文件（jira-cli），可直接在终端中使用，无需 MCP 客户端。

安装

just install-cli
# or
go install github.com/nguyenvanduocit/jira-mcp/cmd/jira-cli@latest

快速开始

export ATLASSIAN_HOST=your-instance.atlassian.net
export [email protected]
export ATLASSIAN_TOKEN=your-api-token
# or
jira-cli --env .env <command> [flags]

命令

命令	描述
get-issue	获取问题详情
search-issues	使用 JQL 搜索问题
create-issue	创建新问题
update-issue	更新现有问题
add-comment	为问题添加评论
list-comments	列出问题的评论
get-transitions	获取可用的状态转换
transition-issue	将问题转换为新状态
list-sprints	列出看板的冲刺
get-worklogs	获取问题的工作日志
add-worklog	记录问题的工作
get-history	获取问题变更历史

示例

# Get an issue
jira-cli get-issue --issue-key PROJ-123

# Search with JQL
jira-cli search-issues --jql "project = PROJ AND status = 'In Progress'" --max-results 20

# Create an issue
jira-cli create-issue --project PROJ --summary "Fix login bug" --type Bug

# Transition issue
jira-cli get-transitions --issue-key PROJ-123
jira-cli transition-issue --issue-key PROJ-123 --transition-id 31

# JSON output
jira-cli search-issues --jql "assignee = currentUser()" --output json | jq '.[].key'

标志

每个命令都接受：

• --env string — .env 文件的路径
• --output string — 输出格式：text（默认）或 json

许可证

MIT — 参见 LICENSE。

面向 AI

本部分仅供 AI 使用

使用此代码库时，请阅读以下文件以了解项目结构：

1. CLAUDE.md - 全面的项目文档，包含架构、开发命令和编码规范
2. main.go - 入口文件，展示 MCP 服务的初始化方式和工具注册方式
3. services/jira_client.go - 单例 Jira 客户端的初始化和身份验证
4. tools/ - 遵循一致模式的各个工具实现
5. docs/ - 详细文档（参见下方结构）

关键概念：

• 这是一个基于 Go 的 MCP 服务，可将 AI 助手连接到 Jira
• 每个工具都遵循注册 + 处理程序模式，并进行类型化输入验证
• 工具按类别组织（问题、冲刺、评论、工作日志等）
• 所有 Jira 操作都使用 github.com/ctreminiom/go-atlassian 客户端库
• 开发原则记录在 .specify/memory/constitution.md 中

进行更改前，请查看：

• CLAUDE.md，了解架构模式和开发命令
• .specify/memory/constitution.md，了解治理原则

快速开始

1) 获取 API 令牌

在 https://id.atlassian.com/manage-profile/security/api-tokens 创建一个。

2) 添加到 Cursor

使用 Docker 或本地二进制文件（STDIO；无需端口）。

Docker

{
  "mcpServers": {
    "jira": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "ATLASSIAN_HOST=https://your-company.atlassian.net",
        "-e", "[email protected]",
        "-e", "ATLASSIAN_TOKEN=your-api-token",
        "ghcr.io/nguyenvanduocit/jira-mcp:latest"
      ]
    }
  }
}

二进制文件

{
  "mcpServers": {
    "jira": {
      "command": "/usr/local/bin/jira-mcp",
      "env": {
        "ATLASSIAN_HOST": "https://your-company.atlassian.net",
        "ATLASSIAN_EMAIL": "[email protected]",
        "ATLASSIAN_TOKEN": "your-api-token"
      }
    }
  }
}

3) 在 Cursor 中试用

• “显示分配给我的问题”
• “ABC 当前冲刺中有哪些内容？”
• “在 ABC 中创建一个 Bug：Safari 上登录失败”

配置

• ATLASSIAN_HOST：https://your-company.atlassian.net
• ATLASSIAN_EMAIL：你的 Atlassian 邮箱
• ATLASSIAN_TOKEN：API 令牌

可选的 .env（本地运行时使用）：

ATLASSIAN_HOST=https://your-company.atlassian.net
[email protected]
ATLASSIAN_TOKEN=your-api-token

HTTP 模式（可选，用于调试）：

jira-mcp -env .env -http_port 3000

Cursor 配置（HTTP 模式）：

{ "mcpServers": { "jira": { "url": "http://localhost:3000/mcp" } } }

限制公开的工具（ENABLED_TOOLS）

默认情况下，所有 Jira 工具都会注册。若要只公开部分工具——例如，为 AI Agent 提供 Jira 的只读视图——请将 ENABLED_TOOLS 环境变量设为以逗号分隔的工具名称允许列表：

ENABLED_TOOLS=jira_get_issue,jira_search_issue,jira_get_comments

规则：

• 未设置或为空 → 公开所有工具（向后兼容）。
• 可容忍名称周围的空格。
• 未知名称会被忽略，但会在启动时记录日志，以便立即发现拼写错误。
• 未列出的名称不会注册，因此 MCP 客户端不会看到这些工具。

只读 Agent 示例（公开 15 个读取工具，禁用全部 8 个修改工具）：

ENABLED_TOOLS=jira_get_issue,jira_search_issue,jira_list_statuses,jira_get_comments,jira_get_issue_history,jira_get_related_issues,jira_list_sprints,jira_get_sprint,jira_get_active_sprint,jira_search_sprint_by_name,jira_get_version,jira_list_project_versions,jira_get_development_information,jira_download_attachment,jira_list_issue_types

安装

Homebrew（macOS/Linux）

brew install nguyenvanduocit/tap/jira-mcp