AI导哈

JIRA集成服务器

MCP JIRA Server是一个为AI工具提供无缝JIRA集成的协议服务器，支持Markdown到ADF格式的自动转换、灵活的字段管理和多站点配置。

  • by codingthefuturewithai
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 codingthefuturewithai/mcp_jira

使用说明

MCP JIRA服务器

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

使用Claude代码快速设置

🚀 让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服务器：

# 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-port 8502 （或其他端口）启动UI时
  • 连接错误：在uvx按需下载软件包时检查您的互联网连接
  • 对于开发，始终使用虚拟环境

平台特定问题：

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

有关详细的故障排除，请参阅 汇流文件.

配置

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
    • 视窗: %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: "automation-user@mycompany.com"
    api_token: "abc123xyz789efg_your_token_here_jkl"
    cloud: true

  dev_jira:
    url: "https://dev-mycompany.atlassian.net"
    email: "dev-automation@mycompany.com"
    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

该项目包括一个基于Streamlit构建的基于web的配置编辑器，可以轻松管理您的 config.yaml 文件。

特性

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

运行编辑器

使用 --ui 使用MCP服务器命令标记以启动配置界面：

# 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问题。您可以修改摘要、描述（支持标记）、受让人、问题类型或其他自定义字段等字段。只有您提供的字段会被更改。

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
  • 视窗: %LOCALAPPDATA%\MCPJira\mcp_jira\Logs\mcp_jira.log （注： %LOCALAPPDATA% 通常决定 C:\Users\<username>\AppData\Local)

配置： 日志行为（级别、文件路径、旋转设置）通过配置 config.yaml 文件。查看示例 config.yaml 有关详细信息，请参阅“配置”部分 log_level, log_file_path, log_max_bytes，以及 log_backup_count.

日志级别也可以使用覆盖 MCP_JIRA_LOG_LEVEL 环境变量。如果设置，此环境变量优先于 log_level 在……里面 config.yaml.

# 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令牌

发展

看 Developpent.md 详细的开发说明，包括：

  • 建立开发环境
  • MCP检验员测试
  • 运行测试
  • 贡献指南
  • 体系结构概述

故障排除

常见问题

身份验证错误

  • 验证API令牌是否正确且尚未过期
  • 确保电子邮件地址与JIRA帐户匹配
  • 检查JIRA实例URL是否可访问

字段错误

  • 使用 additional_fields 用于自定义或可选字段
  • 检查JIRA配置中的字段可用性
  • 服务器优雅地忽略不可用字段

Markdown转换问题

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

连接问题

  • 验证与JIRA实例的网络连接
  • 检查防火墙/代理设置
  • 确保JIRA REST API v3可访问

许可证

该项目根据MIT许可证获得许可。请参阅 许可证 文件以获取详细信息。

作者

用AI编码未来

  • github： 编纂未来
  • 电子邮件：codingthefuturewithai@gmail.com

相关 MCP