MCP JIRA Server

MCP JIRA 服务

一个模型上下文协议（MCP）服务，可为 AI 工具提供无缝的 JIRA 集成。创建和管理 JIRA 问题，支持丰富的 Markdown 格式、自动转换为 Atlassian 文档格式（ADF），以及灵活的字段管理。

使用 Claude Code 快速设置

🚀 让 AI 帮助你设置

复制并粘贴以下提示词之一，发送给你的 AI 编码助手：

获取设置帮助：

Please help me set up the MCP JIRA Server for Claude Code. 
Read the setup guide at: SETUP_ASSISTANT_PROMPT.md

获取用法示例：

Show me how to use MCP JIRA Server effectively.
Read the usage guide at: USAGE_ASSISTANT_PROMPT.md

⚡ 快速安装（如果你知道自己在做什么）

# Install UV if not already installed:
curl -LsSf https://astral.sh/uv/install.sh | sh

# Configure JIRA settings via web UI:
uvx --from ctf-mcp-jira ctf-mcp-jira-server --ui

# Add to Claude Code:
claude mcp add -t stdio mcp_jira "uvx" -- "--from" "ctf-mcp-jira" "ctf-mcp-jira-server"

然后重启 Claude Code。完整说明见下文。

概述

此 MCP 服务可让 AI 助手通过 JIRA REST API v3 直接与 JIRA 实例交互。它负责处理 Markdown 到 ADF 的转换、字段映射和多站点配置等复杂工作，让 AI 工具只需进行最少的设置即可创建格式完善的 JIRA 问题。

主要架构组件：

• MCP 服务：基于 FastMCP 的服务，支持 stdio/SSE 传输
• JIRA 客户端：直接集成 REST API，并处理身份验证
• Markdown 转换器：将 Markdown 转换为 Atlassian 文档格式（ADF）
• 配置系统：支持多站点 JIRA 配置和灵活的站点选择
• 字段管理：支持 JIRA 标准字段和自定义字段

功能

• 丰富的 Markdown 支持：将 Markdown 描述转换为格式规范的 ADF，支持：

  • 标题、段落和文本格式（粗体、斜体、行内代码）
  • 带语法高亮的围栏代码块
  • 项目符号列表和编号列表
  • 表格及复杂格式元素

• 灵活的字段管理：

  • 使用标准字段创建和更新 JIRA 问题：项目、摘要、描述、问题类型。
  • 可靠的经办人处理：提供电子邮件地址，服务会将其解析为正确的 JIRA accountId，以确保分配准确。
  • additional_fields 参数支持标签、优先级、到期日期及其他自定义字段。
  • 对不同 JIRA 配置中不可用的字段进行平滑降级处理。

• 多站点配置：支持配置多个 JIRA 实例和站点别名，可在 config.yaml 中进行配置。

• 全面的错误处理：提供详细的错误消息和日志记录。

• 灵活的传输方式：支持 stdio 和 SSE 两种传输模式。

安装

推荐方式

使用 uvx 运行 MCP JIRA Server，无需持久安装：

# Install UV if not already installed
# macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell):
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Configure JIRA settings via web UI:
uvx --from ctf-mcp-jira ctf-mcp-jira-server --ui

# This launches a web interface at http://localhost:8501 for configuration

uvx 的优势：

• 无需管理持久安装
• 始终在全新、隔离的环境中运行
• 有可用更新时自动下载
• 不会遇到“卸载后重新安装”的问题

**注意：**uvx 首次使用时会下载软件包并将其缓存。后续运行速度更快，但仍会使用全新的环境。

从源代码安装（开发）

# Clone the repository
git clone https://github.com/codingthefuturewithai/mcp_jira.git
cd mcp_jira

# Create and activate a virtual environment using UV
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
uv pip install -e .

安装故障排除

常见问题：

• “找不到命令”：确保已安装 UV，且其位于 PATH 中
• 端口已被占用：启动 UI 时使用 --ui-port 8502（或其他端口）
• 连接错误：检查网络连接，因为 uvx 会按需下载软件包
• 开发时始终使用虚拟环境

特定平台问题：

• Windows：遇到权限错误时，以管理员身份运行 PowerShell
• macOS：如果出现 SSL 错误，请确保已更新证书：brew install ca-certificates
• Linux：可能需要安装其他系统软件包：sudo apt-get install python3-dev

如需详细的故障排除信息，请参阅 Confluence 文档。

配置

JIRA 配置

此服务需要 config.yaml 文件才能连接到你的 JIRA 实例。服务会按以下优先级顺序尝试从这些位置加载此文件：

1. 由命令行参数 --config 指定的路径。
2. 由环境变量 MCP_JIRA_CONFIG_PATH 指定的路径。
3. 操作系统特定的默认用户配置目录：
   • Linux：~/.config/mcp_jira/config.yaml
   • macOS：~/Library/Application Support/mcp_jira/config.yaml
   • Windows：%APPDATA%\MCPJira\mcp_jira\config.yaml（注意：%APPDATA% 通常解析为 C:\Users\<username>\AppData\Roaming）

如果在上述位置都找不到配置文件，服务将自动在操作系统特定的默认路径创建所需目录（如果目录尚不存在）和模板 config.yaml 文件。之后，你需要编辑此模板，填入实际的 JIRA 站点详情。

已填写的 config.yaml 示例：

name: "My Company JIRA Integration"
log_level: "INFO" # Supported levels: DEBUG, INFO, WARNING, ERROR, CRITICAL

default_site_alias: "prod_jira"

sites:
  prod_jira:
    url: "https://mycompany.atlassian.net"
    email: "[email protected]"
    api_token: "abc123xyz789efg_your_token_here_jkl"
    cloud: true

  dev_jira:
    url: "https://dev-mycompany.atlassian.net"
    email: "[email protected]"
    api_token: "another_token_for_dev_environment"
    cloud: true

# Optional: Advanced logging configuration (defaults are usually sufficient)
# log_file_path: "/var/log/custom_mcp_jira/activity.log" # Overrides default log file paths
# log_max_bytes: 20971520  # Max log file size in bytes (e.g., 20MB)
# log_backup_count: 10     # Number of backup log files to keep

JIRA API 令牌

1. 登录你的 JIRA 实例。
2. 前往账户设置（通常需要点击你的头像／个人资料图片）。
3. 前往安全 > API 令牌（具体路径可能因 JIRA 版本而略有不同）。
4. 点击创建 API 令牌。
5. 为令牌设置一个描述性标签（例如：mcp_jira_server_token）。
6. 立即复制生成的令牌。之后将无法再次查看。
7. 将复制的令牌添加到 config.yaml 文件中。

配置编辑器 UI

此项目包含一个基于 Web、使用 Streamlit 构建的配置编辑器，可轻松管理 config.yaml 文件。

功能

• 查看和编辑所有常规设置（服务器名称、日志级别、默认站点别名）。
• 查看、编辑、添加和删除 JIRA 站点配置（别名、URL、电子邮件、API 令牌、云端状态）。
• 更改会直接保存到 MCP 服务使用的 config.yaml 文件中。
• 编辑器会自动采用与服务本身相同的配置文件路径逻辑（CLI 覆盖、环境变量或操作系统特定的默认路径）。

运行编辑器

在 MCP 服务命令中使用 --ui 标志即可启动配置界面：

# Using uvx (recommended - no installation required)
uvx --from ctf-mcp-jira ctf-mcp-jira-server --ui

# Or specify a custom port
uvx --from ctf-mcp-jira ctf-mcp-jira-server --ui --ui-port 8502

浏览器将打开 Streamlit 配置 UI，地址为 http://localhost:8501（或你指定的端口）。

截图

使用方法

运行 MCP 服务

与 Claude Code 搭配使用时，服务会通过快速设置中显示的 claude mcp add 命令自动启动。手动测试或用于其他场景时：

# Run with stdio transport (default) using uvx
uvx --from ctf-mcp-jira ctf-mcp-jira-server

# Run with SSE transport
uvx --from ctf-mcp-jira ctf-mcp-jira-server --transport sse --port 3001

# Use custom configuration file
uvx --from ctf-mcp-jira ctf-mcp-jira-server --config /path/to/config.yaml

# Launch configuration UI
uvx --from ctf-mcp-jira ctf-mcp-jira-server --ui

**注意：**使用 uvx 可确保每次都在全新、隔离的环境中运行服务，避免潜在的依赖冲突。

可用工具

此服务提供以下工具，用于与 JIRA 交互：

create_jira_issue

创建新的 JIRA 问题。你可以指定项目、摘要、Markdown 格式的详细描述（会转换为 JIRA 的富文本格式）、问题类型、经办人及其他自定义字段。

update_jira_issue

更新现有的 JIRA 问题。你可以修改摘要、描述（支持 Markdown）、经办人、问题类型或其他自定义字段等内容。只有你提供的字段会发生更改。

search_jira_issues

使用 JQL（JIRA 查询语言）语法搜索 JIRA 问题。指定 JQL 查询以查找符合条件的问题。

参数：

• query（必填）：用于搜索问题的 JQL 查询字符串
• site_alias（可选）：多站点配置的站点别名
• basic_only（可选，默认值：False）：控制返回的详细程度
  • 当为 False（默认值）时：返回完整的问题数据，包括所有标准字段、问题链接、远程链接、评论和工作日志
  • 当为 True 时：仅返回键、摘要和描述，以提升性能

返回：

• 基本模式：问题键、摘要和描述
• 完整模式：完整的问题详情，包括：
  • 标准字段（项目、类型、状态、优先级、经办人、日期）
  • 问题链接（与其他 JIRA 问题的关系，例如阻塞、被阻塞、关联等）
  • 远程链接（网页链接、Confluence 页面等）
  • 带作者和时间戳的评论
  • 带时间跟踪信息的工作日志

查询示例：

• project = MYPROJECT
• project = MYPROJECT AND status = 'In Progress'
• assignee = currentUser() AND created >= -7d

用法示例：

# Get basic issue information (faster)
search_jira_issues(query="project = ABC", basic_only=True)

# Get comprehensive issue details (default)
search_jira_issues(query="project = ABC AND updated >= -7d")

日志记录

服务会将活动记录到 stderr 和轮转日志文件中。

日志文件位置： 默认情况下，日志文件存储在特定于操作系统的位置：

• macOS：~/Library/Logs/mcp_jira/mcp_jira.log
• Linux：
  • 如果以 root 身份运行：/var/log/mcp_jira/mcp_jira.log
  • 如果以非 root 身份运行：~/.local/state/mcp_jira/mcp_jira.log
• Windows：%LOCALAPPDATA%\MCPJira\mcp_jira\Logs\mcp_jira.log（注意：%LOCALAPPDATA% 通常对应于 C:\Users\<username>\AppData\Local）

配置： 日志记录行为（级别、文件路径、轮转设置）通过 config.yaml 文件配置。有关 log_level、log_file_path、log_max_bytes 和 log_backup_count 的详情，请参阅“Configuration”部分中的 config.yaml 示例。

也可以使用 MCP_JIRA_LOG_LEVEL 环境变量覆盖日志级别。如果设置了此环境变量，其优先级高于 config.yaml 中的 log_level。

# Example: Set log level to DEBUG for detailed API communication
MCP_JIRA_LOG_LEVEL=DEBUG mcp_jira-server

有效的日志级别：DEBUG、INFO（未指定时的默认值）、WARNING、ERROR、CRITICAL。

要求

• Python 3.11 或更高版本（低于 3.13）
• 操作系统：Linux、macOS、Windows
• 可访问 JIRA 实例的网络连接
• 有效的 JIRA API 令牌

开发

详细的开发说明请参阅 DEVELOPMENT.md，包括：

• 设置开发环境
• 使用 MCP Inspector 进行测试
• 运行测试
• 贡献指南
• 架构概览

故障排除

常见问题

身份验证错误

• 确认 API 令牌正确且尚未过期
• 确保电子邮件地址与 JIRA 账户一致
• 检查是否可以访问 JIRA 实例 URL

字段错误

• 对于自定义字段或可选字段，请使用 additional_fields
• 检查字段在 JIRA 配置中是否可用
• 服务会妥善忽略不可用的字段

Markdown 转换问题

• 确保围栏代码块使用正确的语法
• 复杂表格可能需要手动排版
• 查看日志中的转换警告

连接问题

• 确认与 JIRA 实例的网络连接正常
• 检查防火墙／代理设置
• 确保可以访问 JIRA REST API v3

许可证

本项目根据 MIT 许可证授权。详情请参阅 LICENSE 文件。

作者

用 AI 编码未来

• GitHub：codingthefuturewithai
• 电子邮件：[email protected]