Jira CLI MCP Server

Jira CLI MCP 服务

MCP（模型上下文协议）服务，用于封装 jira-cli 命令行工具，让 AI 助手能够与 Jira 交互。

为什么选择 jira-cli-mcp？

如果你正在寻找 Jira MCP 服务，以下是 jira-cli-mcp 的独特之处：

• 🚀 利用现有工具 - 可与你现有的 jira-cli 设置和身份验证无缝协作
• 🔒 安全优先 - 配置文件中无需 API 令牌；身份验证由 jira-cli 处理
• 🪶 轻量 - 仅需运行 Bun 进程，无需 Docker 或容器

什么时候选择 mcp-atlassian？

如果你符合以下情况，请选择 mcp-atlassian：

• 需要 Confluence 支持（本项目仅支持 Jira）
• 更倾向于使用 Docker 部署
• 希望获得无需 CLI 依赖的 独立 解决方案
• 需要 直接 API 集成，而非通过 CLI 封装实现

功能

• create_ticket - 使用可自定义字段创建新的 Jira 工单
• list_tickets - 使用 JQL 查询搜索并列出 Jira 工单
• get_ticket - 获取详细的工单信息，包括评论
• update_ticket_description - 使用富文本格式更新工单描述
• add_comment - 使用 Markdown 为工单添加评论
• assign_to_me - 将工单分配给当前用户
• move_ticket - 将工单移至其他状态
• open_ticket_in_browser - 在默认浏览器中打开 Jira 工单

快速开始

1. 安装并配置 jira-cli（安装指南）：

   # Install jira-cli (macOS)
   brew install ankitpokhrel/jira-cli/jira-cli
   
   # Configure jira-cli with your Jira instance
   jira init
   

2. 安装 jira-cli-mcp：

   brew tap choplin/jira-cli-mcp
   brew install jira-cli-mcp
   

3. 添加到 Claude Desktop 配置中（参见下文的Claude Desktop 设置）

前提条件

• 已安装并完成身份验证的 jira-cli
• Bun 运行时（仅在开发或从源代码安装时需要）

安装

选项 1：通过 Homebrew 安装（macOS/Linux）

brew tap choplin/jira-cli-mcp
brew install jira-cli-mcp

选项 2：通过 npm 安装

# Install globally with npm
npm install -g @choplin/jira-cli-mcp

# Or with Bun
bun install -g @choplin/jira-cli-mcp

选项 3：下载二进制文件

从发布页面下载适用于你平台的预编译二进制文件：

• macOS（Apple Silicon）：jira-cli-mcp-darwin-arm64.tar.gz
• macOS（Intel）：jira-cli-mcp-darwin-x64.tar.gz
• Linux（x64）：jira-cli-mcp-linux-x64.tar.gz
• Linux（ARM64）：jira-cli-mcp-linux-arm64.tar.gz

# Example for macOS (Apple Silicon)
tar -xzf jira-cli-mcp-darwin-arm64.tar.gz
chmod +x jira-cli-mcp-darwin-arm64
sudo mv jira-cli-mcp-darwin-arm64 /usr/local/bin/jira-cli-mcp

选项 4：从源代码构建

git clone https://github.com/choplin/jira-cli-mcp.git
cd jira-cli-mcp
bun install
bun run build:prod

Claude Desktop 设置

选项 1：使用 Homebrew 安装（推荐）

如果你通过 Homebrew 安装（如快速开始所示），请将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "jira-cli": {
      "command": "jira-cli-mcp"
    }
  }
}

选项 2：使用 npm 包

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "jira-cli": {
      "command": "npx",
      "args": ["@choplin/jira-cli-mcp"]
    }
  }
}

或者，如果是全局安装：

{
  "mcpServers": {
    "jira-cli": {
      "command": "jira-cli-mcp"
    }
  }
}

选项 3：使用预编译二进制文件（无依赖项）

1. 从 releases 下载适用于你平台的二进制文件
2. 解压并移动到你的 PATH 中：

tar -xzf jira-cli-mcp-darwin-arm64.tar.gz
sudo mv jira-cli-mcp-darwin-arm64 /usr/local/bin/jira-cli-mcp

1. 添加到配置中：

{
  "mcpServers": {
    "jira-cli": {
      "command": "jira-cli-mcp"
    }
  }
}

选项 4：从源代码构建

1. 克隆并直接运行：

git clone https://github.com/choplin/jira-cli-mcp.git
cd jira-cli-mcp
bun install

1. 添加到配置中：

{
  "mcpServers": {
    "jira-cli": {
      "command": "bun",
      "args": ["run", "/path/to/jira-cli-mcp/src/index.ts"]
    }
  }
}

配置文件位置

配置文件通常位于：

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

验证

完成设置后，重启 Claude Desktop，并询问 Claude 有哪些 Jira 工具可用，以确认 MCP 服务已加载。

其他 AI 助手的设置

Claude Code

Claude Code 内置支持 MCP 服务。要在项目中使用 jira-cli-mcp：

1. 首先，使用安装部分中的任一方法安装 jira-cli-mcp

2. 在项目根目录中创建 .claude/mcp.json 文件：

{
  "servers": {
    "jira-cli": {
      "command": "jira-cli-mcp"
    }
  }
}

1. 重启 Claude Code，MCP 服务将自动加载

然后，你可以在对话中直接使用 Jira 命令，例如：

• “列出我尚未解决的 Jira 工单”
• “显示 PROJ-123 的详细信息”
• “为 PROJ-456 添加评论”

GitHub Copilot（VS Code）

GitHub Copilot 在 Visual Studio Code（1.99 及更高版本）中支持 MCP 服务：

1. 首先，使用安装部分中的任一方法安装 jira-cli-mcp

2. 在仓库中创建 .vscode/mcp.json：

{
  "servers": {
    "jira-cli": {
      "command": "jira-cli-mcp"
    }
  }
}

1. 在 VS Code 中打开 .vscode/mcp.json 文件，然后点击 [Start] 按钮以激活服务

2. 在 Copilot Chat 中：

   • 打开 Copilot Chat 面板
   • 从弹出菜单中选择“Agent”
   • 点击工具图标，查看可用的 MCP 服务

注意：GitHub Copilot 对 MCP 的支持目前处于公开预览阶段。

开发

运行测试

# Run unit tests only
bun test

# Run all tests including integration tests
bun run test:integration

# Run integration tests with a specific test ticket
JIRA_CLI_MCP_TEST_TICKET=PROJ-123 bun run test:integration

环境变量

• JIRA_CLI_PATH - jira-cli 可执行文件的自定义路径（默认值：“jira”）

开发环境变量

• JIRA_CLI_MCP_TEST_TICKET - 集成测试使用的工单键（运行非列表类集成测试时必需）
• INTEGRATION_TEST=true - 启用集成测试

类型检查

bun run typecheck

代码检查与格式化

bun run lint
bun run format

架构

• src/tools/ - MCP 工具实现
• src/utils/ - 共享实用工具和类型
• tests/ - 使用模拟 jira-cli 的单元测试
• tests/integration/ - 使用真实 jira-cli 的集成测试

注意事项

• 服务使用 Atlassian 文档格式（ADF）处理富文本
• jira-cli 会自动将 Markdown 输入转换为 ADF
• 所有集成测试都需要正确的 jira-cli 身份验证

故障排除

常见问题

1. “找不到 jira-cli”错误

   • 确认已安装 jira-cli：which jira
   • 如果使用自定义路径，请设置 JIRA_CLI_PATH 环境变量

2. 身份验证错误

   • 运行 jira me 以验证身份
   • 如有需要，使用 jira init 重新进行身份验证

3. Claude Desktop 中未显示 MCP 服务

   • 确认配置文件路径正确
   • 确保配置中的路径为绝对路径，而非相对路径
   • 更改配置后重启 Claude Desktop

4. macOS 上的权限错误

   • 在“系统设置”中授予终端/Claude Desktop 完全磁盘访问权限
   • 确保 jira-cli 具有必要的权限

调试模式

如需查看详细日志，可以手动运行服务：

cd /path/to/jira-cli-mcp
bun run src/index.ts

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。