jiraMCP (Goroskob)

JiraMCP

MCP服务器包装jira-cli用于LLM集成

JiraMCP提供了一个全面的模型上下文协议（MCP）服务器，它封装了出色的 吉拉cli 该工具使像Claude这样的人工智能助手能够与Jira无缝交互。

特性

• 完成jira-cli集成：通过MCP工具访问所有jira-cli功能
• 基于Docker：打包为Docker镜像，便于部署
• 完全配置支持：支持所有jira-cli配置选项
• Jira服务器和云：适用于Jira服务器/数据中心和Jira Cloud
• 类型安全：使用Python类型提示和Pydantic验证构建
• 综合工具：30多种工具，涵盖问题、史诗、冲刺、项目等

快速开始

先决条件

• Docker已安装在您的系统上
• 使用凭据访问Jira服务器
• Claude Desktop（或其他兼容MCP的客户端）

安装

1. 拉取Docker镜像 （一经发布）：

docker pull ghcr.io/goroskob/jiramcp:latest

或 在当地建造:

git clone https://github.com/goroskob/jiramcp.git
cd jiramcp
docker build -t jiramcp:latest .

1. 配置Claude桌面

添加到您的Claude Desktop配置文件中：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "jiramcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env", "JIRA_SERVER",
        "--env", "JIRA_LOGIN",
        "--env", "JIRA_API_TOKEN",
        "--env", "JIRA_INSTALLATION=Local",
        "--env", "JIRA_AUTH_TYPE=basic",1
        "ghcr.io/goroskob/jiramcp:latest"
      ],
      "env": {
        "JIRA_SERVER": "https://jira.example.com",
        "JIRA_LOGIN": "your.email@example.com",
        "JIRA_API_TOKEN": "your-password-or-token"
      }
    }
  }
}

1. 重新启动克劳德桌面

配置

所需的环境变量

可选环境变量

安装类型

对于Jira服务器/数据中心：

"JIRA_INSTALLATION": "Local"

用途 /rest/api/2/ 端点

对于Jira Cloud：

"JIRA_INSTALLATION": "Cloud"

用途 /rest/api/3/ 端点

身份验证类型

基本身份验证 （最常见）：

"JIRA_AUTH_TYPE": "basic",
"JIRA_API_TOKEN": "your-password"

持有者令牌 （API令牌）：

"JIRA_AUTH_TYPE": "bearer",
"JIRA_API_TOKEN": "your-api-token"

双向TLS （客户证书）：

"JIRA_AUTH_TYPE": "mtls"

输出格式

JiraMCP支持三种输出格式，由 OUTPUT_FORMAT 环境变量：

可用格式：

• plain （默认）-制表符分隔的结构化输出，非常适合程序化解析

- 紧凑高效 - 易于在脚本中解析 - 推荐给AI助手

• json -JSON格式的输出

- 完全结构化的数据 - 最适合与其他工具集成 - 启用高级数据处理

• pretty -人类可读的格式化输出

- 为终端显示着色和格式化 - 非常适合交互式调试 - 人类可读性最高

示例：

# Use plain format (default)
OUTPUT_FORMAT=plain

# Use JSON format for structured data
OUTPUT_FORMAT=json

# Use pretty format for human readability
OUTPUT_FORMAT=pretty

在Claude桌面配置中：

{
  "mcpServers": {
    "jiramcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", ...],
      "env": {
        "JIRA_SERVER": "https://jira.example.com",
        "JIRA_LOGIN": "user@example.com",
        "JIRA_API_TOKEN": "your-token",
        "OUTPUT_FORMAT": "plain"
      }
    }
  }
}

工具范围

您可以使用以下选项选择性地启用工具类别 ENABLED_SCOPES 环境变量。当您只需要特定功能时，这很有用：

可用范围：

• util -实用工具（2个工具： jira_me, jira_serverinfo)
• issue -问题管理工具（12个工具）
• epic -Epic管理工具（4个工具）
• sprint -Sprint管理工具（2个工具）
• project -项目/板/发布工具（4个工具）
• all -启用所有作用域（默认）

示例：

# Enable all tools (default)
ENABLED_SCOPES=all

# Enable only issue and epic tools
ENABLED_SCOPES=issue,epic

# Enable only utility tools (useful for testing connectivity)
ENABLED_SCOPES=util

# Enable project and sprint management only
ENABLED_SCOPES=project,sprint

在Claude桌面配置中：

{
  "mcpServers": {
    "jiramcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", ...],
      "env": {
        "JIRA_SERVER": "https://jira.example.com",
        "JIRA_LOGIN": "user@example.com",
        "JIRA_API_TOKEN": "your-token",
        "ENABLED_SCOPES": "issue,epic"
      }
    }
  }
}

可用工具

实用工具

• jira_me -获取当前经过身份验证的用户
• jira_serverinfo -获取服务器版本和信息

问题管理

• issue_list -使用高级筛选列出和搜索问题
• issue_view -查看详细问题信息
• issue_create -创建新问题
• issue_edit -编辑现有问题
• issue_assign -将问题分配给用户
• issue_move -过渡问题状态
• issue_delete -删除问题
• issue_link / issue_unlink -链接/取消链接相关问题
• issue_clone -克隆/复制问题
• issue_watch -观察/不观察问题
• issue_comment_add -为问题添加评论

Epic管理

• epic_list -列出项目中的史诗
• epic_create -创建新史诗
• epic_add -在史诗中添加问题
• epic_remove -从史诗中删除问题

Sprint管理

• sprint_list -列出冲刺
• sprint_add -创建新的冲刺

项目与董事会管理

• project_list -列出所有可访问的项目
• board_list -列出项目中的板
• release_list -列出版本/发布
• release_create -创建新版本

用法示例

配置后，您可以通过Claude与Jira交互：

You: "List all high-priority bugs in project YSS"

You: "Create a new task in YSS with summary 'Fix login issue' assigned to john.doe"

You: "Show me details for issue YSS-123"

You: "Move YSS-123 to In Progress status"

You: "List all epics in the current sprint"

高级过滤

JQL支持

使用 jql 参数在 issue_list 对于复杂的查询：

# Issues updated in the last week
issue_list(jql="updated >= -7d AND status != Done")

# My open high-priority bugs
issue_list(jql="assignee = currentUser() AND type = Bug AND priority = High AND status != Done")

# Issues in epic
issue_list(jql="parent = YSS-100")

日期筛选

多种日期格式选项：

• 绝对的： yyyy-mm-dd （例如。， 2025-01-15)
• 相对： -10d （10天前）
• 名称： today, week, month, year

状态和标签筛选

# Multiple statuses
issue_list(project="YSS", status=["Open", "In Progress", "Code Review"])

# Multiple labels
issue_list(project="YSS", labels=["backend", "urgent"])

运输选项

JiraMCP支持多种不同用例的传输协议：

STDIO传输（默认）

Claude Desktop和其他MCP客户端使用：

docker run --rm -i \
  -e JIRA_SERVER=https://jira.example.com \
  -e JIRA_LOGIN=user@example.com \
  -e JIRA_API_TOKEN=your-token \
  jiramcp:latest

HTTP传输（流式传输）

对于web服务和基于HTTP的集成：

docker run --rm -d \
  -p 8000:8000 \
  -e JIRA_SERVER=https://jira.example.com \
  -e JIRA_LOGIN=user@example.com \
  -e JIRA_API_TOKEN=your-token \
  jiramcp:latest \
  --transport http --host 0.0.0.0 --port 8000

服务器将在 http://localhost:8000/mcp

苏格兰和南方能源公司运输（传统）

对于服务器发送的事件流：

docker run --rm -d \
  -p 8000:8000 \
  -e JIRA_SERVER=https://jira.example.com \
  -e JIRA_LOGIN=user@example.com \
  -e JIRA_API_TOKEN=your-token \
  jiramcp:latest \
  --transport sse --host 0.0.0.0 --port 8000

使用HTTP传输进行测试

1.初始化MCP会话

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "test-client", "version": "1.0.0"}
    }
  }'

响应包括 mcp-session-id header-将其保存以备后续请求。

2.发送初始化通知

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}'

3.列出可用工具

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

4.呼叫工具

获取当前用户：

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "jira_me",
      "arguments": {}
    }
  }'

查看问题：

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "issue_view",
      "arguments": {
        "issue_key": "PROJ-123",
        "comments": 5
      }
    }
  }'

列出问题：

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "issue_list",
      "arguments": {
        "project": "PROJ",
        "status": ["Open", "In Progress"],
        "paginate": "0:10",
        "columns": "KEY,TYPE,STATUS,SUMMARY"
      }
    }
  }'

使用jq获得漂亮的输出

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}' \
  2>/dev/null | grep '^data:' | cut -d' ' -f2- | jq '.result.tools[] | {name, description}' | head -50

发展

地方发展设置

1. 克隆存储库：

git clone https://github.com/goroskob/jiramcp.git
cd jiramcp

1. 创建 .env 文件：

cat > .env `
1. 验证是否设置了所有必需的环境变量
1. 试着用 `--debug` 详细输出标志

## 安全说明

- **从不提交凭据**：使用环境变量或秘密管理
- **API代币安全**：安全地存储代币，定期轮换
- **TLS验证**：不要禁用TLS验证(`JIRA_INSECURE`)生产中
- **集装箱安全**：以非root用户身份运行容器（默认情况下完成）
- **配置文件**：配置文件是使用限制权限创建的（0600）

## 贡献

欢迎投稿！拜托：

1. 分叉存储库
1. 创建要素分支
1. 通过测试进行更改
1. 提交拉取请求

## 许可证

MIT许可证-有关详细信息，请参阅许可证文件

## 致谢

- 内置于 [FastMCP](https://github.com/jlowin/fastmcp) 马文
- 包裹 [吉拉cli](https://github.com/ankitpokhrel/jira-cli) 作者Ankit Pokhrel
- 灵感来自Anthropic MCP生态系统

## 链接

- **GitHub**: https://github.com/goroskob/jiramcp
- **Docker镜像**：ghcr.io/goroskob/jiramcp
- **吉拉cli**: https://github.com/ankitpokhrel/jira-cli
- **MCP文件**: https://modelcontextprotocol.io

## 支持

- 报告问题：https://github.com/goroskob/jiramcp/issues
- 讨论：https://github.com/goroskob/jiramcp/discussions
- jira cli文档：https://github.com/ankitpokhrel/jira-cli#readme