内容
# @leilashellroot/jira-data-center-mcp
Jira 数据中心 MCP 服务器。连接 AI 助手到自托管 Jira 实例。
## 功能特点
- **问题管理** — 通过 JQL 获取、创建、更新、删除、搜索问题
- **评论** — 添加、编辑、删除、列出评论
- **转换** — 列出可用转换、转换问题
- **WebLinks / Remote links** — 读取和管理外部 URL（GitLab MRs、Confluence 页面、文档）
- **问题链接** — 创建和删除问题之间的链接（Blocks、Relates 等）
- **敏捷** — 看板、冲刺、冲刺问题
- **工作日志** — 获取和添加工作日志条目
- **变更历史** — 查看问题变更历史
- **附件** — 获取元数据、添加文件、删除
- **jira_get_issue_context** — 单次调用返回所有内容：摘要、描述、评论、附件、问题链接、WebLinks、变更历史、父问题、子任务
## 安装
```bash
npm install -g @leilashellroot/jira-data-center-mcp
```
## 配置
最简单的配置使用现有的环境变量：
```bash
export JIRA_BASE_URL=https://jira.example.com
export JIRA_PAT=your-personal-access-token
```
也支持上游兼容的名称：
```bash
export JIRA_HOST=jira.example.com
export JIRA_API_TOKEN=your-personal-access-token
```
`JIRA_HOST` 默认为 HTTPS。如 Jira 在上下文路径下托管，请使用 `JIRA_API_BASE_PATH` 指定完整 URL，例如 `https://jira.example.com/rest`。
### 设置 CLI
设置命令验证凭证并将配置存储在 `~/.atlassian-dc-mcp/jira.env` 中，权限为 `0600`：
```bash
npx @leilashellroot/jira-data-center-mcp setup
```
也支持脚本化设置：
```bash
npx @leilashellroot/jira-data-center-mcp setup --non-interactive \
--host jira.example.com \
--token "$JIRA_TOKEN"
```
配置优先级为：进程环境、`ATLASSIAN_DC_MCP_CONFIG_FILE` 或当前目录 `.env`、主目录配置文件、macOS 密钥链令牌（如果可用）。进程环境变量始终优先。
`JIRA_DEFAULT_PAGE_SIZE` 默认值为 `25`。设置 `ATLASSIAN_DC_MCP_REQUEST_TIMEOUT_MS` 以更改默认的 30 秒 Jira 请求超时。
在 Jira 中生成 PAT：**个人资料 → 个人访问令牌 → 创建令牌**。
## 用法
### 直接
```bash
npx @leilashellroot/jira-data-center-mcp
```
### Claude Desktop
```json
{
"mcpServers": {
"jira": {
"command": "npx",
"args": ["-y", "@leilashellroot/jira-data-center-mcp"],
"env": {
"JIRA_BASE_URL": "https://jira.example.com",
"JIRA_PAT": "your-token"
}
}
}
}
```
### OpenCode / Cursor
```json
{
"mcp": {
"jira": {
"type": "local",
"command": ["npx", "-y", "@leilashellroot/jira-data-center-mcp"],
"environment": {
"JIRA_BASE_URL": "https://jira.example.com",
"JIRA_PAT": "your-token"
},
"enabled": true
}
}
}
```
### 远程 SSE
使用旧 SSE 传输启动服务器：
```bash
MCP_TRANSPORT=sse MCP_HOST=0.0.0.0 MCP_PORT=3000 npx @leilashellroot/jira-data-center-mcp
```
将兼容 SSE 的 MCP 客户端连接到 `http://localhost:3000/sse`。客户端将从 SSE `endpoint` 事件接收 POST 端点。
### 远程 Streamable HTTP
启动当前 MCP 远程传输：
```bash
MCP_TRANSPORT=streamable-http MCP_HOST=0.0.0.0 MCP_PORT=3000 npx @leilashellroot/jira-data-center-mcp
```
将 Streamable HTTP MCP 客户端连接到 `http://localhost:3000/mcp`。
对于 OpenCode 或 Cursor，请使用远程服务器条目代替本地命令：
```json
{
"mcp": {
"jira": {
"type": "remote",
"url": "http://localhost:3000/mcp",
"enabled": true
}
}
}
```
远程配置变量：
| 变量 | 默认值 | 描述 |
|---|---|---|
| `MCP_TRANSPORT` | `stdio` | `stdio`、`sse` 或 `streamable-http` |
| `MCP_HOST` | `127.0.0.1` | HTTP 绑定主机；使用 `0.0.0.0` 进行网络访问 |
| `MCP_PORT` | `3000` | HTTP 端口 |
| `MCP_HTTP_PATH` | `/mcp` | Streamable HTTP 端点 |
| `MCP_SSE_PATH` | `/sse` | SSE 连接端点 |
| `MCP_MESSAGES_PATH` | `/messages` | SSE 消息 POST 端点 |
| `MCP_ALLOWED_HOSTS` | 未设置 | 用于 DNS 绑定保护的逗号分隔 Host 值 |
| `MCP_ALLOWED_ORIGINS` | 未设置 | 用于 DNS 绑定保护的逗号分隔 Origin 值 |
| `MCP_CORS_ORIGIN` | 未设置 | 可选的 `Access-Control-Allow-Origin` 值 |
当绑定到 localhost 以外时，请将服务器置于身份验证和 HTTPS 后。Jira PAT 被服务器用于每个连接的客户端。
## 工具
| 工具 | 描述 |
|---|---|
| `jira_get_issue` | 获取问题详细信息，可选字段投影和扩展 |
| `jira_get_issue_context` | 获取综合上下文 |
| `jira_search_issues` | 使用 JQL、分页、字段投影和扩展搜索 |
| `jira_create_issue` | 创建新问题 |
| `jira_update_issue` | 更新现有问题 |
| `jira_delete_issue` | 删除问题 |
| `jira_add_comment` | 添加评论 |
| `jira_edit_comment` | 编辑评论 |
| `jira_delete_comment` | 删除评论 |
| `jira_get_comments` | 列出评论，分页和渲染扩展 |
| `jira_get_projects` | 列出项目 |
| `jira_get_project` | 获取项目详细信息 |
| `jira_get_issue_types` | 获取项目问题类型 |
| `jira_get_project_versions` | 获取项目版本 |
| `jira_assign_issue` | 指派给用户 |
| `jira_get_current_user` | 获取认证用户 |
| `jira_search_users` | 搜索用户 |
| `jira_get_transitions` | 列出可用转换 |
| `jira_transition_issue` | 转换为新状态，附带字段和更新操作 |
| `jira_get_worklogs` | 获取工作日志条目 |
| `jira_add_worklog` | 添加工作日志 |
| `jira_get_changelog` | 查看变更历史 |
| `jira_get_attachment` | 获取附件元数据 |
| `jira_add_attachment` | 添加文件附件 |
| `jira_delete_attachment` | 删除附件 |
| `jira_get_link_types` | 列出问题链接类型 |
| `jira_create_issue_link` | 链接两个问题 |
| `jira_remove_issue_link` | 删除问题链接 |
| `jira_get_remote_links` | 获取 WebLinks/远程链接 |
| `jira_create_remote_link` | 创建 WebLink |
| `jira_delete_remote_link` | 删除 WebLink |
| `jira_get_agile_boards` | 列出敏捷看板 |
| `jira_get_sprints` | 列出冲刺 |
| `jira_get_sprint_issues` | 获取冲刺问题 |
| `jira_get_board_issues` | 获取看板问题 |
| `jira_search_fields` | 搜索自定义字段 |
| `jira_get_field_options` | 获取自定义字段选项 |
| `jira_get_components` | 获取项目组件 |
| `jira_get_create_meta` | 获取问题创建元数据 |
| `jira_get_dev_status` | 获取开发摘要或详细拉取请求、存储库和分支 |
| `jira_get_filter` | 将筛选器 ID 解析为 JQL、名称、查看 URL |
| `jira_get_filter_issues` | 获取筛选器元数据 + 匹配问题 |
## 要求
- Node.js >= 18
- Jira Server/Data Center 7.0+
## 鸣谢
本项目融合了社区维护的 [Atlassian Data Center MCP](https://github.com/b1ff/atlassian-dc-mcp) 项目的功能创意和工作流程，特别是上游兼容的配置源和设置 CLI、可配置的页面大小和字段投影、详细的开发状态查询、灵活的转换有效载荷、请求超时和凭证验证均从该项目适配而来。上游项目仍在 MIT 许可下独立许可。
### 增强工具参数
- `jira_search_issues`：`startAt`、`maxResults`、`fields` 和 `expand` 为可选。
- `jira_get_issue`：`fields` 和 `expand` 为可选；默认返回精简字段以减少响应大小。
- `jira_get_comments`：`startAt`、`maxResults` 和 `expand` 为可选。
- `jira_update_issue`：支持 `issueTypeId` 和 Jira `update` 操作，除了现有的标准字段。
- `jira_transition_issue`：支持转换屏幕 `fields` 和任意 `customFields`/`update` 有效载荷。
- `jira_get_dev_status`：设置 `detail` 为 `true` 并选择 `dataType`（`pullrequest`、`repository` 或 `branch`）和 `applicationType`（`stash`、`bitbucket`、`github` 或 `githube`）。
## 许可证
MIT
