内容
# jira-mcp
适用于Jira Cloud的通用MCP服务器（stdio）（REST API v3 + Agile 1.0），可用于Claude Code中的任何项目。涵盖问题生命周期、搜索/报告、冲刺、自定义字段、附件、工作日志、链接以及任意API端点的“逃生通道”。
项目无关性：`JIRA_PROJECT_KEY` 是可选的默认值。操作项目的工具接受显式的 `projectKey`，只有在配置了默认值时才会回退。
## 工具（45）
**问题** — `get_issue`，`create_issue`✍，`edit_issue`✍，`delete_issue`⚠，`create_subtask`✍
**搜索/报告** — `search_issues`（自由形式的JQL + 分页），`count_issues`，`group_issues`，`stale_issues`
**工作流程** — `list_transitions`，`transition_issue`✍
**人员** — `assign_issue`✍，`search_users`，`get_current_user`，`list_watchers`，`add_watcher`✍，`remove_watcher`✍
**评论** — `list_comments`，`add_comment`✍，`edit_comment`✍，`delete_comment`⚠
**元数据** — `list_fields`，`get_create_meta`，`get_edit_meta`，`list_projects`，`get_project`
**组织** — `edit_labels`✍，`list_components`，`set_components`✍，`list_link_types`，`link_issues`✍，`delete_link`⚠
**附件/时间** — `list_attachments`，`add_attachment`✍，`delete_attachment`⚠，`list_worklogs`，`add_worklog`✍，`delete_worklog`⚠
**敏捷** — `list_boards`，`list_sprints`，`sprint_issues`，`move_issues_to_sprint`✍，`move_issues_to_backlog`✍，`create_sprint`✍
**通用** — `jira_request`（任意REST方法/路径）
✍ = 写入 · ⚠ = 破坏性操作（需要 `confirm: true`；如果没有它，则返回*干预运行*）
## 亮点
- **无需硬编码的自定义字段：** `list_fields`/`get_create_meta` 会发现字段；`create_issue`/`edit_issue` 接受**按名称或ID**的 `customFields`（名称冲突 → 错误，要求提供ID）。
- **真正的分页搜索：** `search_issues` 使用新端点（`nextPageToken`/`isLast`）；报告会扫描每一页。
- **健壮性：** 在 `429`/`5xx` 时自动重试（尊重 `Retry-After`），标准化Jira错误，内置分页。
- **防护措施：** 每个破坏性操作都需要 `confirm: true`。
## 设置
1. **API令牌：** https://id.atlassian.com/manage-profile/security/api-tokens
2. **构建：**
```bash
cd "jira-mcp"
npm install
npm run build
```
3. **凭证：** `cp .env.example .env` 并填写 `JIRA_BASE_URL`，`JIRA_EMAIL`，`JIRA_API_TOKEN`（以及可选的 `JIRA_PROJECT_KEY` / `JIRA_DEFAULT_ASSIGNEES`）。
4. **烟雾测试：**
```bash
npm run smoke
```
确认身份验证（`/myself`）并在设置了默认项目时列出最多5个问题。
## 在Claude Code中注册
在根目录 `.mcp.json`（键 `jira` → 工具显示为 `mcp__jira__*`）：
```jsonc
{
"mcpServers": {
"jira": {
"command": "node",
"args": ["/path/to/jira-mcp/dist/index.js"],
"env": {
"JIRA_BASE_URL": "https://yourcompany.atlassian.net",
"JIRA_EMAIL": "you@company.com",
"JIRA_API_TOKEN": "your-token",
"JIRA_PROJECT_KEY": "PROJ",
"JIRA_DEFAULT_ASSIGNEES": ""
}
}
}
}
```
重启Claude Code并运行 `/mcp` 以确认 `jira` 已连接。
## 注意事项
- **安全：** `.env` 和 `.mcp.json` 中包含机密信息的文件**不得提交**。如果令牌泄露，请在Atlassian面板中**旋转它**。
- **电子邮件：** Jira Cloud不接受JQL/分配中的直接电子邮件（GDPR）；服务器会自动将电子邮件解析为 `accountId`。
- **写入** 仅在显式调用时发生 - 而破坏性操作需要 `confirm: true`。
- **从v1迁移：** 已弃用的别名（`assign_card`，`get_card`，`comment_card`，`transition_card`，`list_homologacao_cards`）已**删除** - 使用通用等效项（`assign_issue`，`get_issue`，`add_comment`，`transition_issue`，`search_issues`）。将服务器密钥从 `jira-homolog` 重命名为 `jira`时，请更新 `.claude/settings*.json` 中引用 `mcp__jira-homolog__*` 的权限。
