jira-mcp

Jira MCP - 功能最丰富的 Jira MCP 服务

功能强大、功能丰富的 Jira 集成 MCP 服务。 使用模型上下文协议，通过 Cursor、Claude Desktop、Windsurf 和 ChatGPT 等 AI 驱动的大模型客户端控制 Jira。

为什么 Jira MCP 是最佳选择

• 企业级就绪：完全在本地运行，不与第三方共享数据，适合企业环境。
• 功能齐全：可通过自然语言全面控制 Jira，包括创建、更新、搜索、转换和管理工单。
• 轻松设置：提供适用于 Linux、macOS 和 Windows 的预构建二进制文件，几分钟即可开始使用。
• 积极维护：采用 MIT 许可证的开源项目，定期更新并提供社区支持。
• 原生支持 AI：专为模型上下文协议打造，提供出色的 AI 与 Jira 交互体验。

开始使用

Jira MCP 服务

安装

安装 jira-cli

MCP 服务使用 jira-cli 执行 Jira 命令。

请按照适用于你操作系统的安装说明进行操作： https://github.com/ankitpokhrel/jira-cli?tab=readme-ov-file#installation

获取 Jira API 令牌

根据 Jira 的部署方式（Cloud 或自托管），你需要使用不同的身份验证类型。

在此获取 API 令牌：https://id.atlassian.com/manage-profile/security/api-tokens

你需要设置以下环境变量：

• JIRA_API_TOKEN - 你的 Jira API 令牌
• JIRA_AUTH_TYPE - 身份验证类型（令牌使用 bearer，Jira 账户 API 令牌使用 basic，Jira 账户密码使用 password）

建议： 在 MCP 客户端配置中通过 env 字段传递这些变量（见下方配置示例）。这种方式比使用 Shell 环境变量更可靠，因为 Cursor 和 Windsurf 等 GUI 应用不会继承 .bashrc 或 .zshrc 中的变量。

向环境添加凭据的其他方式： https://github.com/ankitpokhrel/jira-cli/discussions/356

启动 Jira CLI

jira init

这会通过提示你输入 Jira URL 和凭据来初始化 Jira CLI。

测试 Jira CLI

jira issue list

这会返回 Jira 中的工单列表。

MCP 服务：选项 1：下载二进制文件（推荐）

从 Releases 页面下载适用于你操作系统的最新版本。

操作系统	二进制文件
Linux	jira-mcp-linux
Windows	jira-mcp-windows.exe
macOS（Apple Silicon）	jira-mcp-macos-apple-silicon-arm64
macOS（Intel）	jira-mcp-macos-x64

Linux

# Download the binary
curl -L -o jira-mcp https://github.com/xcollantes/jira-mcp/releases/latest/download/jira-mcp-linux

# Make it executable
chmod +x jira-mcp

# Move to a directory in your PATH (optional)
sudo mv jira-mcp /usr/local/bin/

添加到你的大模型客户端配置中：

注意： 如果你将二进制文件移到了其他位置，请务必将 /usr/local/bin/jira-mcp 替换为你机器上该文件的路径。

{
  "mcpServers": {
    "jira": {
      "command": "/usr/local/bin/jira-mcp",
      "env": {
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_AUTH_TYPE": "basic"
      }
    }
  }
}

macOS

# For Apple Silicon (M1/M2/M3)
curl -L -o jira-mcp https://github.com/xcollantes/jira-mcp/releases/latest/download/jira-mcp-macos-apple-silicon-arm64

# For Intel Macs
curl -L -o jira-mcp https://github.com/xcollantes/jira-mcp/releases/latest/download/jira-mcp-macos-x64

# Make it executable
chmod +x jira-mcp

# Move to a directory in your PATH (optional)
sudo mv jira-mcp /usr/local/bin/

注意： macOS 可能会在首次运行时阻止该二进制文件。如果看到安全警告，请前往 System Settings > Privacy & Security 并点击 Allow Anyway，或者运行：

xattr -d com.apple.quarantine /usr/local/bin/jira-mcp

添加到你的大模型客户端配置中：

注意： 如果你将二进制文件移到了其他位置，请务必将 /usr/local/bin/jira-mcp 替换为你机器上该文件的路径。

{
  "mcpServers": {
    "jira": {
      "command": "/usr/local/bin/jira-mcp",
      "env": {
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_AUTH_TYPE": "basic"
      }
    }
  }
}

Windows

1. 从发布页面下载 jira-mcp-windows.exe。
2. 将可执行文件移到方便的位置（例如，C:\Program Files\jira-mcp\）。

添加到你的大模型客户端配置中：

{
  "mcpServers": {
    "jira": {
      "command": "C:\\Program Files\\jira-mcp\\jira-mcp-windows.exe",
      "env": {
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_AUTH_TYPE": "basic"
      }
    }
  }
}

注意： 如果你将二进制文件移到了其他位置，请务必将 C:\\Program Files\\jira-mcp\\jira-mcp-windows.exe 替换为你机器上该文件的路径。

MCP 服务：选项 2：使用 uv 搭建开发环境

获取仓库：

git clone https://github.com/xcollantes/jira-mcp.git
cd jira-mcp

将 MCP 服务添加到你选择的大模型客户端中：

注意： 你需要查阅特定客户端的说明，了解如何添加 MCP。

通常，大模型客户端的 JSON 文件如下所示：

{
  "mcpServers": {
    "jira": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/REPO/ROOT",
        "run",
        "python",
        "-m",
        "src.main"
      ],
      "env": {
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_AUTH_TYPE": "basic"
      }
    }
  }
}

这会告知你的大模型客户端应用，有一个工具可以通过调用 uv --directory /ABSOLUTE/PATH/TO/REPO run python -m src.main 来使用。

安装 UV：https://docs.astral.sh/uv/getting-started/installation/

MCP 服务：选项 3：使用 pipx 全局安装

# Install pipx if you haven't already
brew install pipx
pipx ensurepath

# Clone and install the MCP server
git clone https://github.com/xcollantes/jira-mcp.git
cd jira-mcp
pipx install -e .

工作原理

1. 你向 Claude Desktop、Cursor、Windsurf 或 ChatGPT 等大模型客户端输入问题或提示词。
2. 客户端将问题发送给大模型（Sonnet、Grok、ChatGPT）。
3. 大模型分析可用工具，并决定使用哪些工具。
   • 你使用的大模型会了解这些工具的上下文，以及每个工具用途的自然语言描述。
   • 如果不使用 MCP，你也可以在提示词中加入端点及其描述，供大模型“调用”。然后，你可以将文本命令复制并粘贴到机器上的终端中。
   • MCP 提供了更具确定性和标准化的大模型与服务端交互方式。
4. 客户端通过 MCP 服务执行所选工具。
   • MCP 服务可以在你的机器上本地运行，也可以由远程托管 MCP 服务的端点提供。
5. 结果会发送回大模型。
6. 大模型生成自然语言回复，并会发生以下一种或两种情况：
   • 向你显示包含 MCP 服务数据的回复。
   • 使用 MCP 服务执行某项操作。

开发

日志记录

请勿使用 print 语句记录日志。请改用 logging 模块。向 stdout 写入内容会破坏 JSON-RPC 消息并导致服务无法正常运行。

Pre-commit

本项目使用 pre-commit 在每次提交前运行 ruff lint 和格式检查，以及 pytest 测试。

设置 pre-commit 钩子：

uv sync
uv run pre-commit install

安装后，ruff 和 pytest 会在你提交时自动运行。要手动检查所有文件：

uv run pre-commit run --all-files

文档字符串 / 工具装饰器参数

MCP.tools 装饰器参数尤为重要，因为它们是大模型能够理解的文本。这些内容会作为提示词的一部分提供给大模型，并决定何时使用各个工具。

架构

MCP 采用客户端-服务器架构，其中 MCP 主机（如 Cursor 或 ChatGPT 桌面版这样的 AI 应用）会与一个或多个 MCP 服务建立连接。MCP 主机通过为每个 MCP 服务创建一个 MCP 客户端来实现这一点。每个 MCP 客户端都会与对应的 MCP 服务保持专用连接。

https://modelcontextprotocol.io/docs/learn/architecture

常见问题 / 故障排查

编辑 jira-cli 配置文件

在 MacOS 上：

/Users/<your-username>/.config/.jira/.config.yml

使用 jira init 时出现 404 错误

如果使用 jira init 时出现 404 错误，你可能需要编辑 jira-cli 配置文件，使其指向正确的 Jira 实例。身份验证类型只有 3 种可能的值，请逐一尝试：basic、password 或 bearer。