Jira Cloud

Jira云MCP服务器

一种模型上下文协议（MCP）服务器，提供与Jira Cloud交互的工具。该服务器允许像Claude这样的AI助手搜索问题、创建新问题和管理Jira项目。

特性

• 搜索问题：使用JQL（Jira查询语言）查询Jira问题
• 创建问题：使用可自定义字段创建新的Jira问题
• 更新问题：修改问题字段和转换状态
• 评论：添加和检索对问题的评论
• 史诗：列出、创建、更新史诗并检索史诗的所有子问题

项目结构

jira-cloud/
├── index.js                        # Entry point
├── src/
│   ├── server.js                   # Composition root (MCP server wiring)
│   ├── config.js                   # Environment configuration
│   ├── infrastructure/
│   │   └── jira-client.js          # Jira REST API + SDK client
│   └── tools/
│       ├── index.js                # Tool registry
│       ├── get-issues-by-jql.js
│       ├── create-issue.js
│       ├── add-comment.js
│       ├── update-issue.js
│       ├── get-comments.js
│       ├── get-epics.js
│       ├── create-epic.js
│       ├── update-epic.js
│       └── get-epic-issues.js
└── tests/
    ├── unit/                       # Unit tests (no API calls)
    └── integration/                # Integration tests (real Jira)

先决条件

• Node.js v18或更高版本
• Jira Cloud帐户
• A Jira API代币

安装

1. 克隆存储库：

   git clone 
   cd jira-cloud

1. 安装依赖项：

   npm install

1. 创建您的环境配置（见下文）

环境配置

创建一个 .env 使用Jira凭据在项目根目录中创建文件：

JIRA_HOST="https://your-domain.atlassian.net"
JIRA_EMAIL="your-email@example.com"
JIRA_API_TOKEN="your-api-token-here"
JIRA_PROJECT="YOUR-PROJECT-KEY"

如何获取Jira API代币

1. 首选 Atlassian API代币管理
2. 点击 创建API令牌
3. 给您的令牌一个描述性标签（例如“MCP服务器”）
4. 点击 创建
5. 复制生成的令牌并将其粘贴到您的 .env 文件

重要提示：

• 这 JIRA_HOST 必须包括协议(https://)
• 这 JIRA_EMAIL 必须与您的Atlassian帐户电子邮件相匹配
• 这 JIRA_PROJECT 将所有命令作用于单个项目--拒绝其他项目上的操作
• 保持你的 .env 文件安全，从不将其提交到版本控制

示例 .env 文件

JIRA_HOST="https://mycompany.atlassian.net"
JIRA_EMAIL="john.doe@mycompany.com"
JIRA_API_TOKEN="ATATT3xFfGF0..."
JIRA_PROJECT="SCRUM"

运行服务器

本地（用于测试）

node index.js

服务器通过stdio进行通信，因此除非出现错误，否则您将看不到输出。

使用克劳德桌面

将以下配置添加到您的Claude Desktop配置文件中：

窗户： %APPDATA%\Claude\claude_desktop_config.json macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

带WSL的Windows

如果服务器在WSL（Linux的Windows子系统）中运行，请使用以下配置：

{
  "mcpServers": {
    "jira-cloud": {
      "command": "wsl.exe",
      "args": [
        "-d",
        "Ubuntu-24.04",
        "--cd",
        "/home//git/jira-cloud",
        "/home//.nvm/versions/node//bin/node",
        "index.js"
      ],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_PROJECT": "YOUR-PROJECT-KEY"
      }
    }
  }
}

替换：

• `` 使用您的WSL用户名
• ` 使用你的Node.js版本（例如。， v24.13.1`)
• Ubuntu-24.04 如果不同，请使用您的WSL发行版名称

要在WSL中查找Node.js路径，请运行： which node

注： 您可以使用 env 配置中的节（如上所示）或创建 .env 项目目录中的文件。如果两者都存在 env 部分优先。

原生macOS/Linux

{
  "mcpServers": {
    "jira-cloud": {
      "command": "node",
      "args": ["/path/to/jira-cloud/index.js"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_PROJECT": "YOUR-PROJECT-KEY"
      }
    }
  }
}

更新配置后，重新启动Claude Desktop。

可用工具

getIssuesByQL

使用JQL查询获取Jira问题。

参数：

注： 如果JQL还不包含 project 过滤器，服务器会自动预置 project = AND 将结果范围限定到配置的项目。

示例查询：

• assignee = currentUser() -分配给您的问题
• status = "In Progress" -进行中的问题
• created >= -7d -过去7天内产生的问题
• status != Done ORDER BY priority DESC -复杂查询

createIssue

创建一个新的Jira问题。

参数：

注： 仅配置中的问题 JIRA_PROJECT 可以创建。指定其他项目密钥会返回错误。

支持的问题类型： 任务、Bug、故事、史诗（取决于您的项目配置）

addComment

为现有的Jira问题添加评论。

参数：

updateIssue

更新现有Jira问题的字段。

参数：

注： 状态转换取决于项目的工作流配置。

获取评论

获取Jira问题的所有评论。

参数：

getEpics

列出配置的Jira项目中的所有史诗。

参数：

createEpic

在已配置的Jira项目中创建一个新的Epic。

参数：

注： 史诗需要史诗名称字段(customfield_10011)在吉拉。当 epicName 如果省略，则默认为值 summary.

updateEpic

更新现有Epic的字段（摘要、epicName、描述、状态）。

参数：

注： 状态转换取决于项目的工作流配置。

getEpicIssues

获取属于Epic的所有子问题（故事、任务、Bug等）。

参数：

测试

该项目包括单元测试和集成测试，使用 Vitest.

运行单元测试

单元测试在不调用API的情况下验证工具定义、模式和辅助函数。

npm test

或者以观察模式运行以进行开发：

npm run test:watch

运行集成测试

集成测试针对真实的Jira Cloud实例运行。确保你的 .env 文件在运行前已正确配置。

npm run test:integration          # all integration tests (issues + epics)
npm run test:integration:issues   # only issue-related integration tests
npm run test:integration:epics    # only epic-related integration tests
npm run test:all                  # unit tests + all integration tests

警告： 集成测试将在您的项目中创建、修改和删除真正的Jira问题。每次测试后，测试问题都会自动清理。

测试结构

tests/
├── unit/
│   ├── config.test.js              # Config validation tests
│   ├── tool-registry.test.js       # Registry structure and lookup tests
│   └── tools/
│       ├── get-issues-by-jql.test.js
│       ├── create-issue.test.js
│       ├── add-comment.test.js
│       ├── update-issue.test.js
│       ├── get-comments.test.js
│       ├── get-epics.test.js
│       ├── create-epic.test.js
│       ├── update-epic.test.js
│       └── get-epic-issues.test.js
└── integration/
    ├── issues.integration.test.js  # Integration tests for issue tools
    └── epics.integration.test.js   # Integration tests for epic tools

测试覆盖率

自定义集成测试

集成测试使用您可能需要为Jira项目调整的常量：

// tests/integration/issues.integration.test.js
// tests/integration/epics.integration.test.js
const TEST_PROJECT_KEY = 'SCRUM';      // Your project key
const TEST_ISSUE_TYPE_ID = '10003';    // Issue type ID (e.g., Story)

要查找您的问题类型ID，请运行：

curl -u your-email:your-api-token \
  https://your-domain.atlassian.net/rest/api/3/issue/createmeta/YOUR_PROJECT/issuetypes

故障排除

WSL中“node:找不到命令”

从Windows运行时，WSL不会加载您的shell配置文件。使用Node.js的完整路径：

# Find your Node.js path
which node
# Output: /home/username/.nvm/versions/node/v24.13.1/bin/node

在Claude Desktop配置中使用此完整路径。

“401未经授权”错误

• 验证您的API令牌是否正确且未过期
• 确保您的电子邮件与您的Atlassian帐户匹配
• 如果需要，创建一个新的API令牌

搜索时出现“410 Gone”错误

这意味着Jira API已经改变。服务器使用新 /rest/api/3/search/jql 终点。请确保您使用的是此服务器的最新版本。

连接问题

• 验证您的 JIRA_HOST 包括 https://
• 检查您的互联网连接
• 确保您的Jira Cloud实例可访问

许可证

ISC