使用说明

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代币

安装

克隆存储库：

git clone <repository-url>
cd jira-cloud

安装依赖项：
```
npm install
```
创建您的环境配置（见下文）

环境配置

创建一个 .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代币

首选 Atlassian API代币管理
点击 创建API令牌
给您的令牌一个描述性标签（例如“MCP服务器”）
点击创建
复制生成的令牌并将其粘贴到您的 .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/<username>/git/jira-cloud",
        "/home/<username>/.nvm/versions/node/<version>/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"
      }
    }
  }
}

替换：

<username> 使用您的WSL用户名
<version> 使用你的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`	string	Yes	JQL字符串（例如。， `project = TEST`)
`maxResults`	number	No	限制结果（默认值：50）

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

示例查询：

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

createIssue

创建一个新的Jira问题。

参数：

参数	类型	必填	说明
`projectKey`	string	否	项目密钥（例如。， `TEST`).如果省略，则默认为配置的项目。
`summary`	string	是	问题标题
`description`	string	否	问题详细信息
`issueType`	string	否	类型（任务、Bug等）（默认值： `Task`)

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

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

addComment

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

参数：

参数	类型	必填	说明
`issueKey`	string	Yes	问题密钥（例如。， `TEST-123`)
`comment`	string	是	要添加的注释文本

updateIssue

更新现有Jira问题的字段。

参数：

参数	类型	必填	说明
`issueKey`	string	Yes	问题密钥（例如。， `TEST-123`)
`summary`	string	否	新问题标题
`description`	string	否	新问题描述
`status`	string	否	新状态（例如。， `In Progress`, `Done`)

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

获取评论

获取Jira问题的所有评论。

参数：

参数	类型	必填	说明
`issueKey`	string	Yes	问题密钥（例如。， `TEST-123`)

getEpics

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

参数：

参数	类型	必填	说明
`maxResults`	number	否	返回的最大史诗数量（默认值：50）

createEpic

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

参数：

参数	类型	必填	说明
`summary`	string	是	史诗标题
`epicName`	string	否	短Epic名称标签（如果省略，默认为摘要）
`description`	string	否	史诗细节

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

updateEpic

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

参数：

参数	类型	必填	说明
`issueKey`	string	Yes	Epic键（例如。， `TEST-42`)
`summary`	string	否	新史诗标题
`epicName`	string	否	新的Epic短名称标签（customfield_10011）
`description`	string	否	新史诗描述
`status`	string	否	新状态（例如。， `In Progress`, `Done`)

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

getEpicIssues

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

参数：

参数	类型	必填	说明
`epicKey`	string	Yes	Epic键（例如。， `TEST-42`)
`maxResults`	number	否	要返回的最大问题数（默认值：50）

测试

该项目包括单元测试和集成测试，使用 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

测试覆盖率

测试套件	描述
工具定义	验证所有9个工具是否具有正确的模式
getIssuesByQL	测试JQL搜索、分页、错误处理
createIssue	测试问题创建和验证
addComment	向问题添加注释的测试
获取评论	检索评论的测试
updateIssue	测试字段更新和状态转换
getEpics	JQL列出史诗的测试
createEpic	使用epic Name字段测试史诗创作
updateEpic	测试史诗级字段更新和状态转换
getEpicIssues	测试检索史诗的儿童问题
错误处理	测试对无效输入的优雅处理

自定义集成测试

集成测试使用您可能需要为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

使用说明

Jira云MCP服务器

特性

项目结构

先决条件

安装

环境配置

如何获取Jira API代币

示例 .env 文件

运行服务器

本地（用于测试）

使用克劳德桌面

带WSL的Windows

原生macOS/Linux

可用工具

getIssuesByQL

createIssue

addComment

updateIssue

获取评论

getEpics

createEpic

updateEpic

getEpicIssues

测试

运行单元测试

运行集成测试

测试结构

测试覆盖率

自定义集成测试

故障排除

WSL中“node:找不到命令”

“401未经授权”错误

搜索时出现“410 Gone”错误

连接问题

许可证

相关 MCP

DuckDuckGo 搜索 MCP 服务器

图表生成MCP服务器

AI开发助手

必应中文搜索MCP服务器

PostgreSQL管理服务器

网页内容获取工具

示例 `.env` 文件