内容
# jira-mcp
Jira 云的模型上下文协议（MCP）服务器。允许您直接从任何兼容 MCP 的 AI 客户端搜索、创建、更新、转换、分配、删除、评论和记录 Jira 问题的工作。
[](https://github.com/lucasvidela94/jira-mcp)
[](LICENSE)
[](https://github.com/lucasvidela94/jira-mcp/releases)
[](https://goreportcard.com/report/github.com/lucasvidela94/jira-mcp)
---
## 功能
- **完整的 CRUD** 问题 - 创建、读取、更新、删除
- **转换** 问题通过工作流
- **分配** 问题给用户
- **添加评论** 和 **记录工作**
- **JQL 搜索**，可配置结果限制
- **列出项目** 和 **可用转换**
- **冲刺管理** - 列出、获取和搜索 Jira Agile 冲刺
- **设计安全** - 凭证永不被记录、返回或泄露
- **多平台** - macOS、Linux、Windows、ARM64
- **Docker 就绪** - 最小的 `scratch` 镜像
- **HTTP/SSE 传输** - 在受信任的网络中作为远程 MCP 服务器运行
## 安装
### Homebrew（macOS / Linux）
```bash
brew tap lucasvidela94/tap
brew install jira-mcp
```
### 一键安装程序（macOS / Linux）
```bash
curl -fsSL https://raw.githubusercontent.com/lucasvidela94/jira-mcp/master/scripts/install.sh | bash
```
安装程序可以可选地自动配置您的 MCP 客户端。 当在终端中运行时，它会询问您要设置的客户端，提示您输入 Jira URL、用户名和 API 令牌，并写入正确的配置文件。
示例交互流程：
```text
Which MCP client do you want to configure? [opencode/claude/cursor/windsurf/none] (default: opencode):
Jira URL (e.g. https://yourcompany.atlassian.net): https://yourcompany.atlassian.net
Jira username/email: you@example.com
Jira API token:
Proceed? [Y/n] y
```
跳过向导或传递答案作为标志：
```bash
curl -fsSL https://raw.githubusercontent.com/lucasvidela94/jira-mcp/master/scripts/install.sh | bash -s -- --no-configure
```
```bash
curl -fsSL https://raw.githubusercontent.com/lucasvidela94/jira-mcp/master/scripts/install.sh | bash -s -- \
--client opencode \
--jira-url https://yourcompany.atlassian.net \
--jira-username you@example.com \
--jira-api-token your-api-token \
--yes
```
在 https://id.atlassian.com/manage-profile/security/api-tokens 创建或验证您的 Jira API 令牌
### Docker
在本地构建镜像：
```bash
docker build -t jira-mcp .
```
使用您的 Jira 凭证运行：
```bash
docker run -e JIRA_URL=https://yourcompany.atlassian.net \
-e JIRA_USERNAME=you@example.com \
-e JIRA_API_TOKEN=your-api-token \
jira-mcp
```
在容器内使用 HTTP/SSE 传输：
```bash
docker run -p 8080:8080 \
-e JIRA_URL=https://yourcompany.atlassian.net \
-e JIRA_USERNAME=you@example.com \
-e JIRA_API_TOKEN=your-api-token \
jira-mcp --transport http --port 8080
```
已发布的镜像可从 GitHub 容器注册表中获取：
```bash
docker pull ghcr.io/lucasvidela94/jira-mcp:latest
```
### Windows（PowerShell）
```powershell
irm https://raw.githubusercontent.com/lucasvidela94/jira-mcp/master/scripts/install.ps1 | iex
```
PowerShell 安装程序支持相同的可选自动配置，当交互运行时。 要强制或跳过向导，或将值作为参数传递，请先保存脚本：
```powershell
irm https://raw.githubusercontent.com/lucasvidela94/jira-mcp/master/scripts/install.ps1 -OutFile install.ps1
.\install.ps1 -Configure -Client opencode -JiraUrl https://yourcompany.atlassian.net -JiraUsername you@example.com -JiraApiToken your-api-token -Yes
```
### Go 安装
```bash
go install github.com/lucasvidela94/jira-mcp@latest
```
这只安装二进制文件；您仍然需要手动配置您的 MCP 客户端。
### 在运行安装程序之前审查它
如果您更喜欢检查脚本而不是直接将其传输到 shell：
```bash
curl -fsSL https://raw.githubusercontent.com/lucasvidela94/jira-mcp/master/scripts/install.sh -o install.sh
# 检查文件，然后运行它：
bash install.sh
```
或使用内置的检查标志：
```bash
curl -fsSL https://raw.githubusercontent.com/lucasvidela94/jira-mcp/master/scripts/install.sh | bash -s -- --inspect
```
## 配置
设置以下环境变量：
| 变量 | 描述 | 示例 |
|---|---|---|
| `JIRA_URL` | 您的 Jira 云基准 URL | `https://yourcompany.atlassian.net` |
| `JIRA_USERNAME` | Jira 用户的电子邮件 | `you@example.com` |
| `JIRA_API_TOKEN` | Jira API 令牌 | 在此处 [创建](https://id.atlassian.com/manage-profile/security/api-tokens) |
## 客户端设置
<details>
<summary><b>Claude Desktop</b> (<code>~/.config/claude/claude_desktop_config.json</code>)</summary>
```json
{
"mcpServers": {
"jira": {
"command": "jira-mcp",
"env": {
"JIRA_URL": "https://yourcompany.atlassian.net",
"JIRA_USERNAME": "you@example.com",
"JIRA_API_TOKEN": "your-api-token"
}
}
}
}
```
</details>
<details>
<summary><b>Cursor</b> (<code>~/.cursor/mcp.json</code>)</summary>
```json
{
"mcpServers": {
"jira": {
"command": "jira-mcp",
"env": {
"JIRA_URL": "https://yourcompany.atlassian.net",
"JIRA_USERNAME": "you@example.com",
"JIRA_API_TOKEN": "your-api-token"
}
}
}
}
```
</details>
<details>
<summary><b>OpenCode</b> (<code>~/.config/opencode/opencode.json</code>)</summary>
```json
{
"mcp": {
"jira": {
"type": "local",
"command": ["jira-mcp"],
"environment": {
"JIRA_URL": "https://yourcompany.atlassian.net",
"JIRA_USERNAME": "you@example.com",
"JIRA_API_TOKEN": "your-api-token"
}
}
}
}
```
</details>
<details>
<summary><b>Windsurf</b> (<code>~/.config/windsurf/mcp_config.json</code>)</summary>
```json
{
"mcpServers": {
"jira": {
"command": "jira-mcp",
"env": {
"JIRA_URL": "https://yourcompany.atlassian.net",
"JIRA_USERNAME": "you@example.com",
"JIRA_API_TOKEN": "your-api-token"
}
}
}
}
```
</details>
## 工具
| 工具 | 描述 |
|---|---|
| `jira_search` | 使用 JQL 搜索问题 |
| `jira_get_issue` | 按密钥获取问题 |
| `jira_create_issue` | 创建新问题 |
| `jira_update_issue` | 更新现有问题 |
| `jira_transition_issue` | 转换问题 |
| `jira_assign_issue` | 将问题分配给用户 |
| `jira_delete_issue` | 删除问题 |
| `jira_list_projects` | 列出可访问的项目 |
| `jira_get_transitions` | 列出可用转换 |
| `jira_add_comment` | 向问题添加评论 |
| `jira_add_worklog` | 记录问题时间 |
| `jira_list_sprints` | 列出 Jira Agile 看板的冲刺 |
| `jira_get_sprint` | 按 Agile ID 获取冲刺 |
| `jira_get_active_sprint` | 获取看板的活动冲刺 |
| `jira_search_sprint_by_name` | 在看板上按名称搜索冲刺 |
## HTTP/SSE 传输
默认情况下，二进制文件通过 `stdio` 使用 MCP 协议。您也可以将其作为 HTTP/SSE 服务器运行：
```bash
jira-mcp --transport http --port 8080
```
- `GET /sse` 是服务器发送事件的端点。
- `POST /message` 是客户端消息端点。
> **警告：** HTTP/SSE 传输不带有内置身份验证。仅在受信任的网络上运行，并使用您自己的反向代理或 VPN 保护端点。
## 开发
```bash
make test # 运行测试
make test-race # 运行测试并启用竞争检测
make test-cover # 运行测试并启用覆盖率
make build # 构建所有包
make fmt # 格式化代码
make vet # 检查代码
make clean # 删除二进制文件
```
## 发布
使用 [GoReleaser](https://goreleaser.com/) 构建。标记并推送以发布：
```bash
git tag -a v0.1.0 -m "Initial release"
git push origin v0.1.0
```
Homebrew 公式在 `lucasvidela94/homebrew-tap` 自动更新。
## 安全
- **传输中：** 您的 Jira API 令牌仅在 HTTP `Authorization` 头中发送到您的 Jira 云实例。
- **日志中：** 凭证永不被记录，不包含在错误消息中，也不返回在工具结果中。
- **磁盘上：** MCP 客户端将其令牌存储在本地配置文件中。安装程序在该文件上设置 `chmod 600`（Linux/macOS）或限制 ACL 以仅限您的用户（Windows）。
- **审查：** 安装程序是开源的。您可以在运行 `--inspect` 之前或将其下载到文件中进行检查。
- **令牌创建：** 在 https://id.atlassian.com/manage-profile/security/api-tokens 创建或验证您的 Jira API 令牌。
## 许可证
MIT
