内容
# Jira 连接器
Jira Server/Data Center 的 MCP 服务器（REST API v2）。允许 AI 助手（Claude Code，Claude Desktop，...）直接读取和写入您的 Jira。
## 要求
- 一个 Jira Server/Data Center 账户（用户名 + 密码）。
- Node.js 18+。
## 快速开始
使用 Claude Code CLI：
```bash
claude mcp add jira-mcp npx -y g-jira-mcp@latest \
--env JIRA_HOST="https://jira.company.com" \
--env JIRA_USERNAME="your_username" \
--env JIRA_PASSWORD="your_password"
```
或手动添加到 `.claude/settings.json`（或 `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"jira-mcp": {
"command": "npx",
"args": ["-y", "g-jira-mcp@latest"],
"env": {
"JIRA_HOST": "https://jira.company.com",
"JIRA_USERNAME": "your_username",
"JIRA_PASSWORD": "your_password"
}
}
}
}
```
编辑配置后重启 Claude Code/Desktop。
## 环境变量
| 变量名 | 是否必填 | 描述 |
| ----------------------- | -------- | ---------------------------------------------------------------------------------------- |
| `JIRA_HOST` | 是 | 基本 URL，例如 `https://jira.company.com` |
| `JIRA_USERNAME` | 是 | Jira 用户名 |
| `JIRA_PASSWORD` | 是 | Jira 密码 |
| `JIRA_START_DATE_FIELD` | 否 | “开始日期”的自定义字段 ID（默认 `customfield_11300`, 匹配 `pm.gem-corp.tech`） |
在您的实例上发现自定义字段 ID：
```bash
curl -u user:pass https://jira.company.com/rest/api/2/field | jq '.[] | select(.name | test("story|point|start"; "i")) | {id, name}'
```
## 工具
| 工具名 | 描述 | 关键参数 |
| ------------------------ | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `get_ticket` | 通过键值获取 Jira 票据的完整详细信息 | `ticket_id` |
| `search_tickets` | 使用 JQL 查询语言搜索 Jira 票据 | `jql`, `max_results`（可选，默认 50） |
| `create_ticket` | 创建一个新的 Jira 票据（故事、任务、错误、子任务） | `project`, `summary`, `issue_type`, 可选：`body`, `parent_key`, `due_date`, `start_date`, `original_estimate`, `labels` |
| `update_ticket` | 更新 Jira 票据的字段（摘要、描述、类型、父节点、标签、日期、估计、分配人、备注） | `ticket_id`, 可选：`summary`, `description`, `issue_type`, `parent_key`, `labels`, `due_date`, `start_date`, `original_estimate`, `implementation_notes`, `assignee` |
| `transition_ticket` | 通过状态名称更改 Jira 票据的状态 | `ticket_id`, `status` |
| `add_comment` | 添加评论到 Jira 票据 | `ticket_id`, `body` |
| `log_work` | 在 Jira 票据上记录工作（时间） | `ticket_id`, `time_spent`, 可选：`comment`, `started` |
| `link_issues` | 在两个 Jira 票据之间创建链接（例如，阻塞，相关，克隆，重复） | `inward_issue`, `outward_issue`, 可选：`link_type`（默认“阻塞”） |
| `generate_release_notes` | 为修复版本生成 Markdown 释放说明，按问题类型分组 | `fix_version`, 可选：`project` |
### 注意事项
- Jira Server 使用纯文本描述 — 不支持 ADF 格式。
- `duedate` 是一个标准字段（`YYYY-MM-DD`）；“开始日期”是一个自定义字段，可通过 `JIRA_START_DATE_FIELD` 配置。
- `search_tickets` 使用 JQL 语法，例如 `project = GEM AND status = 'In Progress'`。
- `transition_ticket` 通过名称匹配目标状态并自动解析转换 ID。
- `update_ticket` 仅更改您传递的字段；省略字段以保持其当前值。传递 `assignee=""` 以取消分配。`implementation_notes` 追加到描述中。
- `generate_release_notes` 按类型将票据分组为功能 / 改进 / 错误修复 / 其他。
- 所有日志都输出到标准错误流；标准输出流保留给 MCP 协议。
## 示例提示
- “在项目 GEM 中搜索处于进行中的票据”
- “在 GEM 中创建一个标题为‘发行说明 v2.0’的故事，截止日期为 2026-08-01”
- “更新 GEM-234，将分配人设置为 namcp 并添加标签 BugFix”
- “在 GEM-234 中添加评论：‘审查完成’”
- “为项目 GEM 中的修复版本 v2.4 生成发行说明”
## 故障排除
- 401/403：重新检查 `JIRA_USERNAME`/`JIRA_PASSWORD` 以及账户是否可以访问项目。
- 连接/超时：验证 `JIRA_HOST` 格式（以 `https://` 开头，没有尾随 `/`），以及是否需要 VPN/内部网络。
- 开始日期未保存：确认 `JIRA_START_DATE_FIELD` 与您的实例匹配（参见上面的发现命令）。
- 没有错误日志：服务器日志输出到标准错误流 — 检查 MCP 客户端（Claude Code/Desktop）输出，而不是标准输出流。
## 开发
```bash
pnpm install
cp .env.example .env # 使用您的凭证编辑
pnpm build # 通过 esbuild 捆绑到 dist/index.js
pnpm lint # biome 检查 + tsc + prettier（markdown）
pnpm release # release-it：增加版本号，提交，标签，推送（运行 lint + build，首先，无需预提交）
pnpm archive # package release/jira-mcp-v<version>.zip
```
## 支持
有疑问或问题吗？请发送电子邮件至 [NamCP](mailto:namcp@gem-corp.global)。
如果这个项目对您有帮助，请考虑给我买一杯咖啡：
<img src="https://raw.githubusercontent.com/namcpgem/gem-jira-mcp/main/docs/buy-me-a-coffee.jpg" alt="Buy Me A Coffee" width="300">
