Jira MCP Server

这是一个用于Jira集成的模型上下文协议（MCP）服务器。该服务器使像Claude这样的AI助手能够与Jira Cloud实例进行交互。

功能

• 🎫 问题管理（创建、读取、更新、搜索）
• 📋 项目列表
• 🔍 JQL搜索能力
• 🔐 API令牌认证
• 📝 TypeScript实现
• 🖥️ 跨平台支持（Windows、macOS、Linux）

系统要求

• Node.js 18.x或更高版本
• npm 或 yarn
• Jira Cloud实例（不适用于Jira Server/Data Center）

快速开始

1. 安装

npm install

2. 配置

在项目根目录下创建一个.env文件：

JIRA_HOST=your-domain.atlassian.net
JIRA_EMAIL=your-email@example.com
JIRA_API_TOKEN=your-api-token-here

3. 生成API令牌

1. 前往Atlassian账户设置
2. 点击“创建API令牌”
3. 给它一个有意义的标签
4. 将令牌复制到你的.env文件中

4. 构建并运行

npm run build
npm start

可用工具

问题管理

• jira_create_issue - 创建新问题
• jira_get_issue - 获取详细的问题信息
• jira_update_issue - 更新问题字段
• jira_search_issues - 使用JQL搜索问题
• jira_list_projects - 列出所有可访问的项目

示例使用

创建一个问题

{
  "projectKey": "PROJ",
  "summary": "修复登录错误",
  "description": "用户无法使用密码中的特殊字符登录",
  "issueType": "Bug"
}

搜索问题

{
  "jql": "project = PROJ AND status = \"In Progress\" AND assignee = currentUser()",
  "maxResults": 20
}

获取问题详情

{
  "issueKey": "PROJ-123"
}

Claude Desktop配置

将以下内容添加到你的Claude Desktop MCP配置中：

macOS/Linux

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/path/to/jira-mcp-server/build/index.js"],
      "env": {
        "JIRA_HOST": "your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Windows

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["C:\\path\\to\\jira-mcp-server\\build\\index.js"],
      "env": {
        "JIRA_HOST": "your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

认证

使用带有电子邮件+API令牌的基本认证。这是Jira Cloud最安全的方法。

错误处理

服务器包括全面的错误处理功能，针对：

• 无效凭证
• 网络超时
• 无效的JQL查询
• 缺少权限
• 不存在的资源

所有错误都以结构化的格式返回，并附有有用的提示信息。

开发

构建

npm run build

测试

# 测试服务器
node build/index.js

故障排除

常见问题

1. 服务器无法启动：

   • 检查你的.env文件是否正确配置
   • 验证你的API令牌是否有效
   • 确保Node.js版本是18+

2. 权限错误：

   • 验证你的Jira用户是否有适当的权限
   • 检查项目键是否存在且可访问

3. 连接问题：

   • 验证你的Jira主机URL是否正确
   • 检查网络连接到Jira Cloud

许可

ISC

贡献

请参阅CONTRIBUTING.md了解如何为此项目做出贡献的详细信息。

支持

对于问题和功能请求，请使用GitHub问题跟踪器。