AI导哈

JIRA问题管理服务器

一个基于模型上下文协议（MCP）的服务器，提供与JIRA API交互的工具，使AI助手能够通过标准化MCP工具读取、创建、更新和管理JIRA问题。

  • by hackdonalds
  • JavaScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 hackdonalds/jira-mcp

使用说明

JIRA MCP服务器

一种模型上下文协议（MCP）服务器，提供与JIRA API交互的工具。该服务器使AI助手能够通过标准化的MCP工具读取、创建、更新和管理JIRA问题。

特性

此MCP服务器提供以下工具：

  • jira_get_issue：按密钥获取特定JIRA问题的详细信息
  • jira_search：使用支持分页的JQL（JIRA查询语言）搜索问题
  • jira_create_issue：使用项目、问题类型、摘要和可选字段创建新问题
  • jira_update_issue：更新现有问题的字段（摘要、描述、受让人、优先级）
  • jira_transition问题：通过可选注释将问题转换为新状态
  • jira_add_注释：为现有问题添加评论

需求

  • Node.js 18.0或更高版本
  • 具有API令牌访问权限的JIRA实例
  • JIRA实例中的个人访问令牌

安装

选项1：npx快速入门（推荐）

直接运行JIRA MCP服务器，无需安装：

npx @hackdonalds/jira-mcp

选项2：全局安装

全局安装软件包以供重复使用：

npm install -g @hackdonalds/jira-mcp
jira-mcp

选项3：从源代码安装

  1. 克隆此存储库：

    git clone <repository-url>
cd jira-mcp

  2. 安装依赖项：

    npm install

  3. 运行服务器：

    npm start

配置

运行前设置环境变量：

export JIRA_BASE_URL="https://your-jira-instance.com"
export JIRA_API_TOKEN="your-api-token"
export JIRA_EMAIL="your-email@company.com"  # Optional

或者创建一个 .env 文件：

cp .env.example .env
# Edit .env with your JIRA credentials

配置

环境变量

MCP服务器需要以下环境变量：

  • JIRA-BASE_URL：您的JIRA实例URL（没有尾随斜线）
    • 例子： https://yourcompany.atlassian.net 或 https://jira.yourcompany.com
  • JIRA_API_TOKEN公司：您的JIRA个人访问令牌

认证

此服务器使用 承载令牌身份验证 使用个人访问令牌。JIRA_EMAIL环境变量是可选的，仅用于日志记录。

支持的JIRA版本：

  • Atlassian云
  • JIRA服务器9.0+
  • JIRA数据中心

用法

启动服务器

使用npx（如果未全局安装）：

npx @hackdonalds/jira-mcp

如果全局安装：

jira-mcp

来源：

npm start

或者直接运行：

node server.js

工具使用示例

搜索问题

// Search for issues assigned to current user
{
  "tool": "jira_search",
  "arguments": {
    "jql": "assignee = currentUser() AND status != Done",
    "maxResults": 10
  }
}

获取问题详细信息

{
  "tool": "jira_get_issue",
  "arguments": {
    "issueKey": "PROJ-123"
  }
}

创建新问题

{
  "tool": "jira_create_issue",
  "arguments": {
    "project": "PROJ",
    "issueType": "Task",
    "summary": "New task summary",
    "description": "Detailed description of the task",
    "priority": "High"
  }
}

更新问题

{
  "tool": "jira_update_issue",
  "arguments": {
    "issueKey": "PROJ-123",
    "summary": "Updated summary",
    "assignee": "user-account-id"
  }
}

添加评论

{
  "tool": "jira_add_comment",
  "arguments": {
    "issueKey": "PROJ-123",
    "comment": "This is a comment on the issue"
  }
}

日志记录

MCP服务器维护全面的日志记录：

  • 日志文件: mcp.log （在当前目录或系统临时目录中）
  • 日志级别：调试、信息、警告、错误
  • 后备方案：如果文件记录失败，则记录到stderr
  • 内容：API请求、响应、错误和工具执行

错误处理

服务器包括强大的错误处理功能：

  • 缺少配置：优雅的降级，并显示有用的错误消息
  • API错误：JIRA API响应错误的详细日志记录
  • 网络问题：正确的超时和重试处理
  • 文件系统：日志文件创建的自动回退

发展

项目结构

jira-mcp/
├── server.js          # Main MCP server implementation
├── package.json       # Node.js dependencies and scripts
├── .env.example       # Environment variable template
├── .gitignore         # Git ignore rules
├── README.md          # This file
└── mcp.log           # Log file (created at runtime)

测试

设置环境变量并测试服务器：

export JIRA_BASE_URL="https://your-jira-instance.com"
export JIRA_API_TOKEN="your-token-here"

# Test with npx
npx @hackdonalds/jira-mcp

# Or test from source
node server.js

API兼容性

  • 使用JIRA REST API v2(/rest/api/2/)
  • 兼容Atlassian云和服务器安装
  • 支持现代JIRA实例的承载令牌身份验证

故障排除

常见问题

  1. 身份验证错误（401）

    • 验证您的API令牌是否正确且未过期
    • 检查您的JIRA实例是否支持承载令牌身份验证
    • 确保JIRA_BASE_URL正确且可访问

  2. 文件系统错误（EROFS）

    • 服务器自动处理只读文件系统
    • 如果文件记录失败，日志将回退到stderr

  3. 空搜索结果

    • 验证JQL语法是否正确
    • 检查您是否有权限查看问题
    • 尝试一个更简单的查询，如 project is not empty

  4. 网络/超时问题

    • 确保您的JIRA实例可以从网络访问
    • 检查公司防火墙或VPN要求

调试模式

通过设置启用详细日志记录：

export NODE_ENV=development

许可证

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

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 如果适用，添加测试
  5. 提交拉取请求

与 模型上下文协议 TypeScript SDK。

相关 MCP