# @aashari/mcp-server-atlassian-jira 中文文档

规范地址：https://npmcn.com/package/%40aashari/mcp-server-atlassian-jira/

版本：3\.3\.0
npm 元数据更新时间：2025-12-03T06:43:41.080Z
中文译文更新时间：2026-11-05T18:40:44.564Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aashari/mcp-server-atlassian-jira
原文对照：https://npmcn.com/package/%40aashari/mcp-server-atlassian-jira/?lang=original
项目主页：https://github.com/aashari/mcp-server-atlassian-jira#readme
源码仓库：https://github.com/aashari/mcp-server-atlassian-jira

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：236 kB，55 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：9 个
- 首次发布：2025-03-23T12:08:36.971Z
- 最新版本发布：2025-12-03T06:43:40.876Z
- 近 30 天下载量：58640（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：108（近 12 个月 5 个）

## 中文简介

为Atlassian Jira服务的Node.js/TypeScript MCP服务器. Equips AI系统(LLMs)有列表/获取项目,搜索/处理问题(使用JQL/ID),并查看dev信息(承诺,PRs)的工具. 将AI能力直接连接到Jira项目管理中并发布 tracki

## 安装

```sh
npm install @aashari/mcp-server-atlassian-jira
```

也可以使用：`pnpm add @aashari/mcp-server-atlassian-jira`、`yarn add @aashari/mcp-server-atlassian-jira`、`bun add @aashari/mcp-server-atlassian-jira`

## README

# 连接 AI 到您的 Jira 项目

通过将克洛德,Cursor AI,以及其他AI助手直接连接到你的Jira项目,问题和工作流程来转变你的管理和跟踪工作方式. 获得即时项目见解,精简议题管理,加强团队协作.

[![NPM Version](https://img.shields.io/npm/v/@aashari/mcp-server-atlassian-jira)](https://www.npmjs.com/package/@aashari/mcp-server-atlassian-jira)

## 你能做什么吗

-   **询问AI您的项目**:"DEV项目中的活性问题是什么"
-   **获得问题见解**"给我看看PROJ-123的细节 包括评论"
-   **跟踪项目进度**"列出分配给我的所有高度优先问题"
-   **管理问题评论**:"向PROJ-456添加关于测试结果的评论"
-   **跨项目搜索**:"在我的项目中查找所有正在运行中的错误"
-   **创建和更新问题**:"在MOBILE计划中创建新错误"

## 完美为

-   **开发者** 需要迅速了解问题细节和发展背景的人
-   **项目管理员** 跟踪进展情况、优先事项和团队任务
-   **Scrum 大师** 管理短跑和工作流程状态
-   **团队领导** 监测项目健康和解决问题
-   **QA 工程师** 跟踪错误和测试状态
-   **谁都行** 希望用自然语言与吉拉互动

## 快速启动

两分钟后起床跑道:

### 1\. 获得你的Jira证书

生成 Jira API 键 :

1.  转到 [地图集API 键](https://id.atlassian.com/manage-profile/security/api-tokens)
2.  点击 **创建 API 令牌**
3.  给它一个名字像 **阿联酋助理**
4.  **复制生成的令牌** 立刻,你不会再看到它了

### 2\. 立即尝试

```bash
# Set your credentials
export ATLASSIAN_SITE_NAME="your-company"  # for your-company.atlassian.net
export ATLASSIAN_USER_EMAIL="your.email@company.com"
export ATLASSIAN_API_TOKEN="your_api_token"

# List your Jira projects
npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/project/search"

# Get details about a specific project
npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/project/DEV"

# Get an issue with JMESPath filtering
npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/issue/PROJ-123" --jq "{key: key, summary: fields.summary, status: fields.status.name}"
```

## 连接到 AI 助理

### 对于 Claude 桌面用户

将此添加到您的 Claude 配置文件( E)`~/.claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-jira"],
      "env": {
        "ATLASSIAN_SITE_NAME": "your-company",
        "ATLASSIAN_USER_EMAIL": "your.email@company.com",
        "ATLASSIAN_API_TOKEN": "your_api_token"
      }
    }
  }
}
```

重新启动克洛德桌面,你可以看到状态栏中的jira服务器.

### 其他助理助理

大多数AI助手支持MCP. 在全球安装服务器 :

```bash
npm install -g @aashari/mcp-server-atlassian-jira
```

然后配置您的 AI 助手使用 STIO 传输的 MCP 服务器 .

### 选项: 配置文件

创建 `~/.mcp/configs.json` 全系统配置:

```json
{
  "jira": {
    "environments": {
      "ATLASSIAN_SITE_NAME": "your-company",
      "ATLASSIAN_USER_EMAIL": "your.email@company.com",
      "ATLASSIAN_API_TOKEN": "your_api_token"
    }
  }
}
```

**替代配置密钥 :** 系统还接受 `"atlassian-jira"`, (中文(简体) ), `"@aashari/mcp-server-atlassian-jira"`,或 `"mcp-server-atlassian-jira"` 改为 `"jira"`。 。 。 .

## 可用工具

这个MCP服务器提供了5个通用工具,可以访问任何Jira API端点:

| 工具 | 说明 |
| --- | --- |
| `jira_get` | 获取任何 Jira API 端点( 读取数据) |
| `jira_post` | POST 到任何终点( 创建资源) |
| `jira_put` | PUT 到任意终点(替换资源) |
| `jira_patch` | PATCH 任意终点( 部分更新) |
| `jira_delete` | DELETE 任意终点( 调走资源) |

### 常见 API 路径

**项目:**

-   `/rest/api/3/project/search` - 列出所有项目
-   `/rest/api/3/project/{projectKeyOrId}` - 获取项目细节

**问题:**

-   `/rest/api/3/search/jql` - 与JQL的搜索问题(使用) `jql` 查询段落)
-   `/rest/api/3/issue/{issueIdOrKey}` - 获取问题的细节
-   `/rest/api/3/issue` - 创建(POST)
-   `/rest/api/3/issue/{issueIdOrKey}/transitions` - 获得/完成过渡

**评论:**

-   `/rest/api/3/issue/{issueIdOrKey}/comment` - 清单/补充评论
-   `/rest/api/3/issue/{issueIdOrKey}/comment/{commentId}` - 获得/更新/删除评论

**工作日志 :**

-   `/rest/api/3/issue/{issueIdOrKey}/worklog` - 清单/添加工作日志
-   `/rest/api/3/issue/{issueIdOrKey}/worklog/{worklogId}` - 获得/更新/删除工作日志

**用户状态( S) :**

-   `/rest/api/3/myself` - 获取当前用户
-   `/rest/api/3/user/search` - 搜索用户(使用) `query` (第1款)
-   `/rest/api/3/status` - 列出所有状态
-   `/rest/api/3/issuetype` - 清单问题类型
-   `/rest/api/3/priority` - 列出优先事项

### JMESPath 过滤

所有工具都支持可选 JMESPath (`jq`过滤以提取具体数据:

```bash
# Get just project names and keys
npx -y @aashari/mcp-server-atlassian-jira get \
  --path "/rest/api/3/project/search" \
  --jq "values[].{key: key, name: name}"

# Get issue key and summary
npx -y @aashari/mcp-server-atlassian-jira get \
  --path "/rest/api/3/issue/PROJ-123" \
  --jq "{key: key, summary: fields.summary, status: fields.status.name}"
```

## 现实世界实例

### 探索您的项目

问你的人工智能助手:

-   _"列出我所有的项目"_
-   _"告诉我关于DEV计划的细节"_
-   _"什么项目里有‘平面'这个词?"_

### 搜索和跟踪问题

问你的人工智能助手:

-   _"在DEV项目中找到所有高度优先的问题"_
-   _"给我看看分配给我的问题"_
-   _"搜索上个星期报告的虫子"_
-   _"为机动队列出所有公开问题"_

### 管理问题细节

问你的人工智能助手:

-   _详细了解PROJ-456 包括评论_
-   _"PROJ-123目前的状况和受让人是什么?"_
-   _“ 忽略认证错误上的所有注释 ”_

### 问题沟通

问你的人工智能助手:

-   _"给PROJ-456添加一则评论:"代码审查完成,准备测试"_
-   _"关于登入问题的评论 它被部署在中转"_

## CLI 命令

CLI 镜像 MCP 直接终端访问的工具 :

```bash
# GET request
npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/project/search"

# GET with query parameters
npx -y @aashari/mcp-server-atlassian-jira get \
  --path "/rest/api/3/search/jql" \
  --query-params '{"jql": "project=DEV AND status=\"In Progress\"", "maxResults": "10"}'

# POST request (create an issue)
npx -y @aashari/mcp-server-atlassian-jira post \
  --path "/rest/api/3/issue" \
  --body '{"fields": {"project": {"key": "DEV"}, "summary": "New issue title", "issuetype": {"name": "Task"}}}'

# POST request (add a comment)
npx -y @aashari/mcp-server-atlassian-jira post \
  --path "/rest/api/3/issue/PROJ-123/comment" \
  --body '{"body": {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": "My comment"}]}]}}'

# PUT request (update issue - full replacement)
npx -y @aashari/mcp-server-atlassian-jira put \
  --path "/rest/api/3/issue/PROJ-123" \
  --body '{"fields": {"summary": "Updated title"}}'

# DELETE request
npx -y @aashari/mcp-server-atlassian-jira delete \
  --path "/rest/api/3/issue/PROJ-123/comment/12345"
```

## 解决问题

### "校正失败"或"403紫禁"

1.  **检查您的 API 调试权限**数字 :
    
    -   转到 [地图集API 键](https://id.atlassian.com/manage-profile/security/api-tokens)
    -   确定你的代币还在使用中, 并且还没有过期
2.  **校验您的站点名称格式**数字 :
    
    -   如果你的吉拉URL是 `https://mycompany.atlassian.net`
    -   你的网站名应该只是 `mycompany`
3.  **测试您的证书**数字 :
    
    ```bash
    npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/myself"
    ```
    

### "未找到资源"或"404"

1.  **检查 API 路径**数字 :
    
    -   路径对大小写敏感
    -   使用工程密钥( 例如 ), `DEV`(不是项目名称)
    -   问题键包括项目前缀(例如, `DEV-123`(中文(简体) )
2.  **验证访问权限**数字 :
    
    -   确保您在浏览器中访问工程
    -   一些项目可能仅限于某些用户

### 搜索时找不到结果

1.  **尝试不同的搜索术语**数字 :
    
    -   使用工程密钥而不是工程名称
    -   尝试更广泛的搜索标准
2.  **检查 JQL 语法**数字 :
    
    -   在 Jira 的高级搜索中先验证您的 JQL

### Claude 桌面整合问题

1.  **重新启动 Claude 桌面** 更新配置文件后
2.  **验证配置文件位置**数字 :
    -   马可斯: `~/.claude/claude_desktop_config.json`
    -   窗口 : `%APPDATA%\Claude\claude_desktop_config.json`

### 获取帮助

如果你仍然有问题:

1.  运行一个简单的测试命令来验证所有工作
2.  检查 [GitHub 问题](https://github.com/aashari/mcp-server-atlassian-jira/issues) 类似的问题
3.  以错误消息创建新问题并设置细节

## 经常被问到的问题

### 我需要什么许可?

您的Atlassian账户需要:

-   **进入吉拉** 包含您想要查询的项目的适当权限
-   **API 令牌** 拥有适当的许可(在创建时自动授予)

### 我可以用这个与Jira Server (premise)?

目前,此工具只支持 **吉拉·云**. Jira Server/Data Center的支持可在未来版本中添加.

### 我该怎么找到我的网站名?

您的网站名称是您的 Jira URL 的第一部分 :

-   URL : `https://mycompany.atlassian.net` - > 站点名称: `mycompany`
-   URL : `https://acme-corp.atlassian.net` - > 站点名称: `acme-corp`

### 人工智能助理是做什么工作的?

任何支持模式背景协议的AI助手:

-   克劳德桌面
-   光标AI
-   继续. dev
-   许多其他

### 我的数据安全吗?

没错! 此工具 :

-   完全运行在您的本地机器上
-   用你自己的Jira证书
-   从不向第三方发送数据
-   只访问您允许它访问的内容

### 我可以搜索多个项目吗?

没错! 使用JQL查询进行跨项目搜索. 例如:

```bash
npx -y @aashari/mcp-server-atlassian-jira get \
  --path "/rest/api/3/search/jql" \
  --query-params '{"jql": "assignee=currentUser() AND status=\"In Progress\""}'
```

## 从 v2.x 迁移

3.0版本用5个通用的HTTP方法工具来取代8+特定工具. 如果你从v2.x升级:

**在(v2.x)之前:**

```
jira_ls_projects, jira_get_project, jira_ls_issues, jira_get_issue,
jira_create_issue, jira_ls_comments, jira_add_comment, jira_ls_statuses, ...
```

**在(v3.0)之后:**

```
jira_get, jira_post, jira_put, jira_patch, jira_delete
```

**移徙实例:**

-   `jira_ls_projects` - > (中文) `jira_get` 有路径 `/rest/api/3/project/search`
-   `jira_get_project` - > (中文) `jira_get` 有路径 `/rest/api/3/project/{key}`
-   `jira_get_issue` - > (中文) `jira_get` 有路径 `/rest/api/3/issue/{key}`
-   `jira_create_issue` - > (中文) `jira_post` 有路径 `/rest/api/3/issue`
-   `jira_add_comment` - > (中文) `jira_post` 有路径 `/rest/api/3/issue/{key}/comment`
-   `jira_ls_statuses` - > (中文) `jira_get` 有路径 `/rest/api/3/status`

## 支助

需要帮忙吗? 如何获得援助:

1.  **检查上面的故障排除区域** - 涉及最常见的问题
2.  **访问 GitHub 仓库** 文件和实例: [github.com/aashari/mcp-server-atlassian-jira 页面存档备份,存于互联网档案馆](https://github.com/aashari/mcp-server-atlassian-jira)
3.  **报告问题** 时间 [GitHub 问题](https://github.com/aashari/mcp-server-atlassian-jira/issues)
4.  **开始讨论** 专题请求或一般问题

* * *

_照顾希望将AI带入项目管理流程的团队._

## 常见问题

### @aashari/mcp-server-atlassian-jira 是什么？

为Atlassian Jira服务的Node\.js/TypeScript MCP服务器\. Equips AI系统\(LLMs\)有列表/获取项目,搜索/处理问题\(使用JQL/ID\),并查看dev信息\(承诺,PRs\)的工具\. 将AI能力直接连接到Jira项目管理中并发布 tracki

### 如何安装 @aashari/mcp-server-atlassian-jira？

在项目目录运行 npm install @aashari/mcp-server-atlassian-jira，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mcp-atlassian-jira，可以用 npx mcp-atlassian-jira 直接运行。

### @aashari/mcp-server-atlassian-jira 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aashari/mcp-server-atlassian-jira 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @aashari/mcp-server-atlassian-jira 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @aashari/mcp-server-atlassian-jira 可以商用吗？

@aashari/mcp-server-atlassian-jira 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @aashari/mcp-server-atlassian-jira 的下载量有多少？

根据 npm 官方下载统计，@aashari/mcp-server-atlassian-jira 在 2026/10/05 – 2026/11/03 这 30 天内被下载 58,640 次，日均约 1,955 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aashari/mcp-server-atlassian-jira 还在维护吗？

最新版本 3\.3\.0 发布于 2025/12/03（11 个月前）；至今共发布 108 个版本，其中过去 12 个月发布了 5 个；首次发布于 2025/03/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。