使用说明

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的客户端）

安装

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

docker pull ghcr.io/goroskob/jiramcp:latest

或 在当地建造:

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

配置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"
      }
    }
  }
}

重新启动克劳德桌面

配置

所需的环境变量

变量	描述	示例
`JIRA_SERVER`	Jira服务器URL	`https://jira.example.com`
`JIRA_LOGIN`	用户名或电子邮件	`john.doe@example.com`
`JIRA_API_TOKEN`	密码或API令牌	`your-password-here`

可选环境变量

变量	默认值	描述
`JIRA_INSTALLATION`	`Local`	`Local` 对于服务器/DC， `Cloud` Jira Cloud
`JIRA_AUTH_TYPE`	`basic`	身份验证类型： `basic`, `bearer`，或 `mtls`
`JIRA_PROJECT_KEY`	-	默认项目密钥（例如。， `PROJ`)
`JIRA_PROJECT_TYPE`	-	项目类型： `scrum` 或 `kanban`
`JIRA_BOARD_NAME`	-	默认板名
`JIRA_FORCE_TTY`	`true`	强制TTY模式
`JIRA_DEBUG`	`false`	启用调试日志记录
`JIRA_INSECURE`	`false`	跳过TLS验证（不推荐）
`OUTPUT_FORMAT`	`plain`	输出格式： `plain`, `json`，或 `pretty`
`ENABLED_SCOPES`	`all`	要启用的工具范围（见下文）

安装类型

对于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

发展

地方发展设置

克隆存储库：

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

创建 .env 文件：

cat > .env << EOF
JIRA_SERVER=https://jira.example.com
JIRA_LOGIN=your.email@example.com
JIRA_API_TOKEN=your-password-here
JIRA_INSTALLATION=Local
EOF

使用docker compose构建并运行：

docker-compose up --build

测试只读操作

为了安全测试，请仅使用只读工具：

jira_me -获取当前用户
jira_serverinfo -获取服务器信息
issue_view -查看问题详细信息
issue_list -列出问题
epic_list -列出史诗
sprint_list -列出冲刺
project_list -列出项目
board_list -列表板
release_list -列出版本

项目结构

jiramcp/
├── src/
│   └── jiramcp/
│       ├── __init__.py
│       ├── server.py          # Main FastMCP server
│       ├── config.py           # Configuration management
│       ├── cli_wrapper.py      # jira-cli command execution
│       └── tools/              # MCP tool implementations
│           ├── issues.py       # Issue management tools
│           ├── epics.py        # Epic tools
│           ├── sprints.py      # Sprint tools
│           ├── projects.py     # Project/board tools
│           └── utils.py        # Utility tools
├── tests/                      # Unit tests
├── Dockerfile                  # Docker image definition
├── docker-compose.yml          # Development setup
└── pyproject.toml             # Python package config

运行测试

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=jiramcp --cov-report=html

故障排除

身份验证错误（403）

问题: Authentication failed (403)

解决方案:

验证凭据是否正确
检查是否需要验证码-在浏览器中通过Jira URL解决
对于Jira Cloud，请确保您使用的是API令牌，而不是密码

未找到错误（404）

问题: Resource not found (404)

解决方案:

检查 JIRA_INSTALLATION 设置：
- 使用 Local Jira服务器/数据中心
- 使用 Cloud Jira Cloud
验证资源（问题、项目等）是否存在
检查您是否有访问资源的权限

错误的请求错误（400）

问题: Bad request (400)

解决方案:

首先在Jira web UI中验证JQL语法
检查字段值是否对Jira实例有效
确保提供必填字段

连接问题

问题：无法连接到Jira服务器

解决方案:

验证 JIRA_SERVER URL正确且可访问
检查网络连接
对于自签名证书，设置 JIRA_INSECURE=true （不建议用于生产）

Docker问题

问题：Docker容器无法启动

解决方案:

检查Docker是否正在运行： docker ps
查看日志： docker logs <container-id>
验证是否设置了所有必需的环境变量
试着用 --debug 详细输出标志

安全说明

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

贡献

欢迎投稿！拜托：

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

许可证

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

致谢

内置于 FastMCP 马文
包裹吉拉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

使用说明

JiraMCP

特性

快速开始

先决条件

安装

配置

所需的环境变量

可选环境变量

安装类型

身份验证类型

输出格式

工具范围

可用工具

实用工具

问题管理

Epic管理

Sprint管理

项目与董事会管理

用法示例

高级过滤

JQL支持

日期筛选

状态和标签筛选

运输选项

STDIO传输（默认）

HTTP传输（流式传输）

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

使用HTTP传输进行测试

1.初始化MCP会话

2.发送初始化通知

3.列出可用工具

4.呼叫工具

使用jq获得漂亮的输出

发展

地方发展设置

测试只读操作

项目结构

运行测试

故障排除

身份验证错误（403）

未找到错误（404）

错误的请求错误（400）

连接问题

Docker问题

安全说明

贡献

许可证

致谢

链接

支持

相关 MCP

DuckDuckGo 搜索 MCP 服务器

图表生成MCP服务器

AI开发助手

GitLab项目管理服务器

必应中文搜索MCP服务器

Primavera P6 XER文件解析服务器