AI导哈

Jira集成服务器

一个提供与Jira全面集成的模型上下文协议（MCP）服务器，使AI助手能够通过标准化接口与Jira交互，实现问题搜索、创建、更新和管理。

  • by garimiddisuman
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 garimiddisuman/jira-mcp

使用说明

Jira MCP服务器

提供与Jira全面集成的模型上下文协议（MCP）服务器。该服务器使AI助手能够通过标准化的界面与Jira交互，允许他们以编程方式搜索、创建、更新和管理Jira问题。

特性

此MCP服务器为Jira集成提供了以下工具：

  • 🔍 搜索问题 -使用JQL（Jira查询语言）搜索问题
  • 📄 获取问题详细信息 -检索有关特定问题的详细信息
  • ➕ 创建问题 -在任何项目中创建新问题
  • ✏️ 更新问题 -修改现有问题字段
  • 💬 添加评论 -为问题添加评论
  • 🔄 获取过渡 -查看可用的状态转换
  • ⚡ 过渡问题 -更改问题状态/工作流状态
  • 👤 分配问题 -将问题分配给用户
  • 📋 列出项目 -获取所有可访问的项目
  • 🔎 搜索用户 -按姓名或电子邮件查找用户
  • 📝 获取评论 -检索问题的所有评论
  • 📊 获取董事会 -列出所有可访问的Scrum和看板板
  • 📈 获取董事会问题 -从特定板检索问题

先决条件

在开始之前，请确保您已经：

  • 已安装Node.js 18或更高版本
  • Jira帐户（云或数据中心）
  • Jira API证书（电子邮件和API令牌）
  • Claude Desktop或其他兼容MCP的客户端

安装

1.克隆或下载

git clone <repository-url>
cd jira-mcp

或者，如果您在此目录中从头开始，则文件已经创建。

2.安装依赖项

npm install

这将安装：

  • @modelcontextprotocol/sdk -用于构建服务器的MCP SDK
  • axios -Jira API调用的HTTP客户端
  • dotenv -环境变量管理
  • TypeScript和Node.js类型定义

3.建设项目

npm run build

这将TypeScript代码编译为JavaScript build/ 目录。

配置

步骤1：获取Jira API代币

  1. 登录您的Jira帐户 https://your-domain.atlassian.net
  2. 首选 账户设置 → 安全 → API令牌
  3. 点击 创建API令牌
  4. 给它一个标签（例如“MCP服务器”），然后单击 创建
  5. 立即复制令牌 （您将无法再看到它）

步骤2：创建环境文件

创建一个 .env 根目录中的文件：

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

重要提示：

  • JIRA_HOST 应该只是没有的域名 https://
  • 使用与您的Jira帐户关联的电子邮件
  • 保持API令牌的安全，并且永远不要将其提交给版本控制

步骤3：配置Claude桌面

将服务器添加到Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

视窗: %APPDATA%\Claude\claude_desktop_config.json

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

替换 /ABSOLUTE/PATH/TO/jira-mcp 使用项目目录的实际绝对路径。

步骤4:重新启动克劳德桌面

完全退出并重新启动Claude Desktop以使更改生效。

用法

配置后，您可以要求Claude使用自然语言与Jira交互。以下是一些示例：

查询示例

搜索问题

"Find all open bugs in the PROJ project"
"Show me issues assigned to me that are in progress"
"Search for issues created this week with high priority"

在幕后，Claude将使用JQL，如下所示：

  • project = PROJ AND type = Bug AND status = Open
  • assignee = currentUser() AND status = "In Progress"
  • created >= -1w AND priority = High

获取问题详细信息

"Show me the details of issue PROJ-123"
"What's the status of PROJ-456?"

创建新问题

"Create a new bug in project PROJ with summary 'Login page not loading' and description 'Users cannot access the login page'"
"Create a task in PROJ called 'Update documentation' with high priority"

更新问题

"Update PROJ-123 to change the summary to 'Fix login page loading issue'"
"Change the priority of PROJ-456 to High"

添加评论

"Add a comment to PROJ-123 saying 'This has been fixed in the latest release'"
"Comment on PROJ-456: 'Waiting for QA team to verify'"

过渡问题

"Move PROJ-123 to In Progress"
"Close PROJ-456"

对于转换，Claude将首先使用以下命令获取可用的转换 jira_get_transitions，然后执行相应的操作。

分配问题

"Assign PROJ-123 to john.doe@example.com"
"Unassign PROJ-456"

您需要用户的帐户ID，Claude可以使用该ID找到 jira_search_users.

列出项目

"What Jira projects do I have access to?"
"Show me all available projects"

搜索用户

"Find user john.doe"
"Search for users named Smith"

获取董事会

"Show me all available boards"
"List all Scrum boards"
"What boards do I have access to?"

获取董事会问题

"Show me all issues from board 123"
"Get all stories from the development board"
"List issues from board 456 that are in progress"

可用工具参考

jira_search_问题

使用JQL搜索问题。

参数：

  • jql （必填）：JQL查询字符串
  • maxResults （可选）：最大结果（默认值：50）
  • startAt （可选）：起始索引（默认值：0）

例子：

{
  "jql": "project = PROJ AND status = Open",
  "maxResults": 10
}

jira_get_issue

获取有关问题的详细信息。

参数：

  • issueKey （必填）：发布密钥（例如“PROJ-123”）

例子：

{
  "issueKey": "PROJ-123"
}

jira_create_issue

创建新问题。

参数：

  • projectKey （必填）：项目密钥
  • summary （必填）：问题摘要
  • issueType （必填）：问题类型（Bug、任务、故事等）
  • description （可选）：问题描述
  • priority （可选）：优先级（高、中、低等）

例子：

{
  "projectKey": "PROJ",
  "summary": "Fix login bug",
  "issueType": "Bug",
  "description": "Login page not loading",
  "priority": "High"
}

jira_update_issue

更新现有问题。

参数：

  • issueKey （必填）：问题密钥
  • summary （可选）：更新摘要
  • description （可选）：更新的描述
  • priority （可选）：更新优先级

例子：

{
  "issueKey": "PROJ-123",
  "summary": "Updated summary",
  "priority": "High"
}

jira_add_注释

为问题添加评论。

参数：

  • issueKey （必填）：问题密钥
  • comment （必填）：评论文本

例子：

{
  "issueKey": "PROJ-123",
  "comment": "This has been fixed"
}

jira_get_转换

获取问题的可用转换。

参数：

  • issueKey （必填）：问题密钥

例子：

{
  "issueKey": "PROJ-123"
}

jira_transition问题

将问题转换为新状态。

参数：

  • issueKey （必填）：问题密钥
  • transitionId （必填）：转换ID（来自get_transitions）

例子：

{
  "issueKey": "PROJ-123",
  "transitionId": "31"
}

jira_assign_issue

将问题分配给用户。

参数：

  • issueKey （必填）：问题密钥
  • accountId （必填）：用户帐户ID（使用null取消分配）

例子：

{
  "issueKey": "PROJ-123",
  "accountId": "5d123456789abc0def123456"
}

jira_get_项目

获取所有可访问的项目。无需参数。

jira_search_users

搜索用户。

参数：

  • query （必填）：搜索查询（姓名或电子邮件）

例子：

{
  "query": "john.doe"
}

jira_get_注释

获取某个问题的所有评论。

参数：

  • issueKey （必填）：问题密钥

例子：

{
  "issueKey": "PROJ-123"
}

jira_get_boards

获取所有可访问的Jira板（Scrum和看板）的列表。

参数：

  • startAt （可选）：起始索引（默认值：0）
  • maxResults （可选）：最大结果（默认值：50）

例子：

{
  "startAt": 0,
  "maxResults": 50
}

jira_get_board_issues

从特定的Jira董事会获取问题。可用于从板中检索故事、任务和错误。

参数：

  • boardId （必填）：板ID号
  • startAt （可选）：起始索引（默认值：0）
  • maxResults （可选）：最大结果（默认值：50）
  • jql （可选）：JQL过滤器适用于板问题

例子：

{
  "boardId": 123,
  "jql": "type = Story AND status = 'In Progress'",
  "maxResults": 20
}

发展

项目结构

jira-mcp/
├── src/
│   ├── index.ts          # Main MCP server implementation
│   └── jira-client.ts    # Jira API client wrapper
├── build/                # Compiled JavaScript (generated)
├── package.json          # Project dependencies
├── tsconfig.json         # TypeScript configuration
├── .env                  # Environment variables (create this)
├── .gitignore           # Git ignore rules
└── README.md            # This file

可用脚本

  • npm run build -将TypeScript编译为JavaScript
  • npm run watch -开发观看模式
  • npm run dev -使用Node.js调试器运行

进行更改

  1. 在中编辑TypeScript文件 src/
  2. 跑 npm run build 编写
  3. 重新启动Claude Desktop以测试更改

故障排除

服务器未出现在Claude中

  1. 检查路径是否正确 claude_desktop_config.json 绝对正确
  2. 验证 build/index.js 文件存在（运行 npm run build)
  3. 完全退出并重新启动Claude Desktop（而不仅仅是关闭窗口）
  4. 检查Claude Desktop日志是否有错误

身份验证错误

  • 验证您的 JIRA_HOST 不包括 https://
  • 确认您的API令牌有效且尚未过期
  • 确保电子邮件与您的Jira帐户匹配
  • 检查您的帐户是否有权访问Jira实例

API错误

  • 检查项目密钥和问题密钥是否正确（区分大小写）
  • 验证您是否有执行该操作的权限
  • 某些操作可能需要特定的Jira权限
  • 查看工具返回的错误消息

JQL查询问题

  • 首先在Jira的搜索界面中测试JQL
  • 确保字段名正确，如果包含空格，请加引号
  • 使用正确的JQL运算符（=、！=、IN、NOT IN等）
  • 常见字段： project, status, assignee, priority, type, created, updated

安全说明

  • 永远不要承诺你的 .env 文件或API内标识
  • API令牌具有与您的用户帐户相同的权限
  • 考虑为自动化创建一个专用服务帐户
  • 定期轮换您的API代币
  • 对所有敏感数据使用环境变量

JQL参考

常见JQL示例：

# Issues in a project
project = PROJ

# Open bugs
project = PROJ AND type = Bug AND status = Open

# Assigned to me
assignee = currentUser()

# High priority issues
priority = High

# Created recently
created >= -7d

# Multiple conditions
project = PROJ AND status IN (Open, "In Progress") AND assignee = currentUser()

API费率限制

Jira Cloud有速率限制：

  • 每位用户每秒10个请求
  • 考虑对批量操作实施延迟
  • 服务器处理单个请求；批处理操作可能会达到极限

许可证

麻省理工学院

支持

对于问题和疑问：

  • 检查上面的故障排除部分
  • 审查Jira API文档：https://developer.atlassian.com/cloud/jira/platform/rest/v3/
  • 审查MCP文件：https://modelcontextprotocol.io

贡献

欢迎投稿！拜托：

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 提交拉取请求

备注：这是一个非官方工具，不隶属于Atlassian或得到Atlassian的认可。

相关 MCP