SuBlog/content/posts/jira-cli-intro/index.md

---
title: jira_cli — 把企业 Jira 装进命令行，AI Agent 直接调用
published: 2026-07-17
updated: 2026-07-17
description: 介绍 jira_cli，一个开源的企业 Jira CLI 命令行工具和MCP，支持 Jira Server / Data Center，自带 MCP stdio server，让 Claude Code、Codex 等 AI 编程工具直接读写 Jira 任务。
image: /posts/jira-cli-intro/img/cover.svg
tags: ['Jira', 'CLI', 'MCP', 'Go', 'AI Agent', '效率工具']
difficulty: 入门
---

## jira_cli 是什么

[jira_cli](https://github.com/yourname/jira_cli) 是一个面向企业 Jira（Server / Data Center）的本地命令行工具，Go 语言编写，MIT 协议开源。它同时提供 **Cobra CLI** 和 **MCP stdio server** 两种入口，既能当日常命令行用，又能直接接入 AI 编程工具。

```bash
# CLI 日常使用
jira_cli issue search "project = PROJ ORDER BY updated DESC"
jira_cli issue get PROJ-123
jira_cli issue comment PROJ-123 "处理完成，请测试验证"

# MCP 模式 — 给 AI 装上操作 Jira 的手
jira_cli mcp --user=work
```

## 为什么需要它

大多数 Jira 命令行工具只解决"开发者手动操作 Jira"这一个场景。但 2026 年 AI 编程工具已经普及，你的 AI Agent（Claude Code、Codex、Cursor 等）也需要读写 Jira。痛点就来了：

| 痛点 | jira_cli 怎么解 |
|------|---------------|
| 企业 Jira 在内网，没有公网 API | 本地 stdio MCP server，不经过外网 |
| AI 可能误删、误写 Jira 数据 | 账号级只读策略，AI 只能查不能改 |
| 团队多人多 Jira 实例 | 多 Profile 管理，`--user=work` 切换 |
| Windows 终端体验差 | 原生 `.exe` 构建 + 一键安装脚本 |
| AI 生成 JQL 困难 | 字段元数据发现：`field list --query xxx` |
| MCP 直接拿原始 JSON 太冗长 | 紧凑视图 + `--view summary` 减少 token 消耗 |

## 安装

```bash
# 从源码安装（要求 Go 1.26.3+）
go install github.com/yourname/jira_cli@latest

# 或下载预编译二进制
# https://github.com/yourname/jira_cli/releases
```

Windows 用户下载 zip 包解压后双击 `install.bat` 即可全局安装，自动加入 PATH。

## 快速上手

### 1. 配置认证

```bash
# 设置 Jira 地址
jira_cli set base-url https://jira.your-company.com --global

# Token 认证（推荐）
jira_cli set token <your-token> --global

# 或用户名密码认证
jira_cli set auth <username> <password> --global

# 验证一下
jira_cli user me
```

### 2. 日常使用

```bash
# 查自己今天的任务
jira_cli issue search "assignee = currentUser() ORDER BY updated DESC"

# 看某个任务详情
jira_cli issue get PROJ-123

# 流转状态
jira_cli issue transitions PROJ-123                    # 可以转哪些
jira_cli issue do-transition PROJ-123 21               # 执行流转

# 添加备注
jira_cli issue comment PROJ-123 "已定位到问题，正在修复"

# 创建任务
jira_cli issue create PROJ Task --fields @fields.json
```

### 3. 配给 AI 使用

```bash
# 先配置一个只读账号给 AI 用
jira_cli set base-url https://jira.your-company.com --name ai --global
jira_cli set token <token> --name ai --global
jira_cli set readonly on --name ai --global
```

然后在 AI 工具的 MCP 配置里加上：

```json
{
  "mcpServers": {
    "jira": {
      "command": "jira_cli",
      "args": ["mcp", "--user=ai"]
    }
  }
}
```

这样 AI 就能查 Jira 但不能修改，既有了上下文，又不用担心误操作。

## 亮点

### 1. 账号级只读策略

这是 jira_cli 最实用的设计。给 AI Agent 配置只读账号：

```bash
jira_cli set readonly on --name ai
```

只读模式下：
- CLI 写命令被隐藏和拒绝
- MCP 的写入工具不会注册
- 环境变量 `JIRA_READONLY=true` 也可以临时覆盖

AI 只能查 JQL、看任务、查字段、读评论，绝对不会误改数据。需要创建/更新时，另配一个有写入权限的账号由开发者自己操作。

### 2. 多 Profile 切换

一个配置文件里管理多个 Jira 账号，`--user` 切换：

```bash
# 工作账号
jira_cli set base-url https://jira.company.com --name work --global
jira_cli set token <work-token> --name work --global

# 个人账号
jira_cli set base-url https://jira.personal.com --name personal --global
jira_cli set token <personal-token> --name personal --global

# 使用时切换
jira_cli --user=work issue search "project = PROJ"
jira_cli --user=personal issue search "project = SIDE"
```

同时支持**项目级配置**（`--local`）和工作目录绑定：

```bash
# 在项目目录下，配置只对当前项目生效
cd ~/projects/backend
jira_cli set base-url https://jira-backend.company.com --local
```

### 3. 对 AI 友好的输出

jira_cli 在输出设计上充分考虑了 AI Agent 的 token 消耗：

```bash
# 紧凑视图 — 去掉 self/avatar/缩略图等无用字段
jira_cli issue get PROJ-123 --view summary

# 表格输出 — 一眼看到关键信息
jira_cli issue search "project = PROJ" --output table

# JSON 输出 — 程序解析，不转义 Unicode
jira_cli --output json issue get PROJ-123

# 自定义搜索列 — 只要需要的字段
jira_cli set search-columns key,summary,fixVersions
```

### 4. 字段元数据发现

Jira 的 customfield 让人头疼，jira_cli 提供了完整的字段发现能力：

```bash
# 列出所有字段及其类型
jira_cli field list

# 搜索包含特定关键词的字段
jira_cli field list --query "版本"

# 只看自定义字段
jira_cli field list --custom-only

# 创建任务前，先看看需要哪些字段
jira_cli issue create-meta PROJ --issue-type Task

# 分页查看可选值
jira_cli issue create-meta-values PROJ Task priority --query High
```

### 5. MCP 写入控制

除了全局只读，MCP 还有更细粒度的控制：

| 环境变量 | 作用 |
|----------|------|
| `JIRA_CREATE_OPEN=false` | 禁用创建/更新工具 |
| `JIRA_DISABLE_DISCLAIMER=true` | 去掉 AI 自动添加的备注声明 |
| `JIRA_CREATE_SUMMARY_MAX` | 限制摘要长度 |
| `JIRA_CREATE_DESCRIPTION_MAX` | 限制描述长度 |
| `JIRA_CREATE_FIELDS_MAX_BYTES` | 限制创建字段的 JSON 大小 |

这些限制确保 AI 即使有写入权限也不会"失控"——例如防止 AI 往描述里塞几万字的废话。

### 6. 中英双语帮助

帮助信息默认中文，也支持一键切英文：

```bash
# 保存英文偏好
jira_cli set help-language en

# 切回中文
jira_cli set help-language zh

# 临时覆盖
jira_cli --lang en issue search -h
```

## 架构一览

```
main.go
  cmd/                         CLI 命令、MCP 启动、访问策略
  internal/config/             运行时配置、Profile 持久化
  internal/tools/jira_tools/   MCP 输入/输出适配层
  pkg/jira/                    可复用的 Jira REST 客户端
```

设计原则清晰：

- **`pkg/jira`** 是纯 Jira 客户端，HTTP、认证、上下文处理都在这里
- **`cmd`** 只管 Cobra 解析和呈现
- **`internal/tools/jira_tools`** 只管 MCP schema 验证和结果适配
- **`internal/config`** 拥有 Profile 的全部逻辑，不分散到 cmd

每一层职责单一，新增 Jira 能力时按 `endpoints.go → Client 方法 → CLI 命令 → MCP tool → 策略注册` 的路径走就行。

## 和已有方案的对比

| 方案 | 适合场景 | jira_cli 的区别 |
|------|---------|---------------|
| Atlassian Rovo MCP Server | Jira Cloud、官方 OAuth | jira_cli 是本地 stdio，适合内网 Server/DC |
| go-jira / jira-cli 社区版 | 纯命令行管理 | jira_cli 同时提供 MCP server，面向 AI 工作流 |
| 直接调 REST API | 自定义集成 | jira_cli 封装了认证、只读策略、字段元数据 |
| Jira 网页 | 日常使用 | jira_cli 把 Jira 变成终端里的一行命令 |

## 总结

如果你的团队满足以下任一条件，jira_cli 值得一试：

- 企业 Jira 部署在内网，想接入 AI 编程工具
- 想给 AI Agent 只读权限来查 Jira 上下文
- 需要命令行快速查看/操作 Jira，不想切浏览器
- 需要管理多个 Jira 实例和多套账号
- Windows 用户想要无摩擦的 CLI 体验

GitHub：[github.com/yourname/jira_cli](https://github.com/yourname/jira_cli) | MIT 协议 | Go 1.26.3+