Atlassian Jira MCP Server

将AI连接到Jira项目

通过将Claude、Cursor AI和其他AI助手直接连接到Jira项目、问题和工作流，改变您管理和跟踪工作的方式。获得即时的项目见解，简化问题管理，增强团队协作。

](https://www.npmjs.com/package/@aashari/mcp-server-atlassian-jira)

你能做什么

• 向AI询问您的项目：“DEV项目中的活跃问题是什么？”
• 获取问题见解：“显示PROJ-123的详细信息，包括评论”
• 跟踪项目进度：“列出分配给我的所有高优先级问题”
• 管理问题评论：“在PROJ-456中添加关于测试结果的评论”
• 跨项目搜索：“查找我的项目中正在进行的所有bug”
• 创建和更新问题：“在MOBILE项目中创建一个新错误”

非常适合

• 开发者 需要快速访问问题细节和开发背景的人员
• 项目经理 跟踪进度、优先级和团队任务
• Scrum大师 管理冲刺和工作流状态
• 团队领导 监控项目健康状况和问题解决
• QA工程师 跟踪bug和测试状态
• 任何人 谁想用自然语言与Jira互动

快速开始

2分钟后起床跑步：

1.获取Jira证书

生成Jira API令牌：

1. 首选 大西洋API代币
2. 点击 创建API令牌
3. 给它起个名字，比如 “AI助手”
4. 复制生成的令牌 立即（你不会再看到它了！）

2.立即尝试

# 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配置文件中(~/.claude/claude_desktop_config.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"
      }
    }
  }
}

重新启动Claude Desktop，您将在状态栏中看到jira服务器。

其他AI助理

大多数AI助手都支持MCP。全局安装服务器：

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

然后配置您的AI助手，使其使用带有STDIO传输的MCP服务器。

替代方案：配置文件

创建 ~/.mcp/configs.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端点：

常见的API路径

项目：

• /rest/api/3/project/search -列出所有项目（分页，推荐）
• /rest/api/3/project -列出所有项目（非分页、遗留）
• /rest/api/3/project/{projectKeyOrId} -获取项目详细信息

问题：

• /rest/api/3/search/jql -JQL的搜索问题（使用 jql 查询参数）。 重要： /rest/api/3/search 已弃用！
• /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} -获取/更新/删除工作日志

用户和状态：

• /rest/api/3/myself -获取当前用户
• /rest/api/3/user/search -搜索用户（使用 query 参数）
• /rest/api/3/status -列出所有状态
• /rest/api/3/issuetype -列出问题类型
• /rest/api/3/priority -列出优先级

TOON输出格式

默认情况下，所有响应都使用 TOON（面向令牌的对象表示法） 与JSON相比，该格式将令牌使用量减少了30-60%。TOON使用表格数组和最少的语法，使其成为人工智能消费的理想选择。

要改用JSON： 添加 --output-format json 到CLI命令或设置 outputFormat: "json" 在MCP工具调用中。

TOON与JSON示例：

TOON: key|summary|status
      PROJ-1|First issue|Open
      PROJ-2|Second issue|Done

JSON: [{"key":"PROJ-1","summary":"First issue","status":"Open"},
       {"key":"PROJ-2","summary":"Second issue","status":"Done"}]

JMESPath过滤

所有工具都支持可选的JMESPath(jq)过滤以提取特定数据：

# 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}"

响应截断和原始日志

对于大型API响应（>40k个字符≈10k个令牌），响应将自动截断并提供指导。完整的原始响应保存到 /tmp/mcp/mcp-server-atlassian-jira/-.txt 以供参考。

截断后，您将看到：

• 带有原始文件路径的截断通知
• 使用更好的过滤器优化查询的建议
• 显示的数据百分比与总大小

真实世界的例子

探索您的项目

问你的AI助手：

• *“列出我有权访问的所有项目”*
• *“显示DEV项目的详细信息”*
• *“哪些项目包含‘平台’一词？”*

搜索和跟踪问题

问你的AI助手：

• *“查找DEV项目中的所有高优先级问题”*
• *“显示分配给我的正在处理的问题”*
• *“搜索上周报告的错误”*
• *“列出移动团队的所有未决问题”*

管理问题详细信息

问你的AI助手：

• *“获取有关PROJ-456问题的完整详细信息，包括评论”*
• *“PROJ-123的当前状态和受让人是什么？”*
• *“显示关于身份验证错误的所有评论”*

问题沟通

问你的AI助手：

• *在PROJ-456中添加注释：“代码审查已完成，准备进行测试”*
• *“对已部署到登台的登录问题发表评论”*

CLI命令

CLI镜像MCP工具以实现直接终端访问：

# GET request (returns TOON format by default)
npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/project/search"

# GET with query parameters and JSON output
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"}' \
  --output-format json

# GET with JMESPath filtering to extract specific fields
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}"

# 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"}}'

# PATCH request (partial update)
npx -y @aashari/mcp-server-atlassian-jira patch \
  --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"

注： 所有CLI命令都支持：

• --output-format -从中选择 toon （默认，令牌有效）或 json
• --jq -使用JMESPath表达式筛选响应
• --query-params -将查询参数作为JSON字符串传递

故障排除

“身份验证失败”或“403禁止”

1. 检查您的API代币权限:

- 首选 大西洋API代币 - 确保您的令牌仍然有效且未过期

1. 验证您的网站名称格式:

- 如果你的Jira URL是 https://mycompany.atlassian.net - 您的网站名称应该只是 mycompany

1. 测试您的凭据:

   npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/myself"

“找不到资源”或“404”

1. 检查API路径:

- 路径区分大小写 - 使用项目密钥（例如。， DEV)不是项目名称 - 问题密钥包括项目前缀（例如。， DEV-123)

1. 验证访问权限:

- 确保您可以在浏览器中访问该项目 - 某些项目可能仅限于某些用户

搜索时“未找到结果”

1. 尝试不同的搜索词:

- 使用项目密钥而不是项目名称 - 尝试更广泛的搜索条件

1. 检查JQL语法:

- 首先在Jira的高级搜索中验证您的JQL

Claude桌面集成问题

1. 重新启动克劳德桌面 更新配置文件后
2. 验证配置文件位置:

- macOS： ~/.claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json

获取帮助

如果你仍然有问题：

1. 运行一个简单的测试命令来验证一切正常
2. 检查 对于类似的问题
3. 使用错误消息和设置详细信息创建新问题

常见问题

我需要什么权限？

您的Atlassian帐户需要：

• 访问Jira 具有要查询的项目的适当权限
• API令牌 具有适当的权限（创建权限时自动授予）

我可以将其与Jira服务器（内部部署）一起使用吗？

目前，该工具仅支持 吉拉云.Jira服务器/数据中心支持可能会在未来的版本中添加。

我如何找到我的网站名称？

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

• 网址： https://mycompany.atlassian.net ->站点名称： mycompany
• 网址： https://acme-corp.atlassian.net ->站点名称： acme-corp

这与哪些AI助手一起工作？

任何支持模型上下文协议（MCP）的AI助手：

• 克劳德桌面版
• 光标AI
• Continue.dev
• 许多其他

我的数据安全吗？

对！此工具：

• 完全在本地计算机上运行
• 使用您自己的Jira凭据
• 切勿将您的数据发送给第三方
• 仅访问您授予其访问权限的内容

我可以搜索多个项目吗？

对！使用JQL查询进行跨项目搜索。例如：

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

技术细节

最近的更新

版本3.2.1 （2025年12月）：

• 添加了TOON输出格式，可减少30-60%的令牌
• 为大型有效载荷（>40k个字符）实现了自动响应截断
• 原始API响应保存到 /tmp/mcp/mcp-server-atlassian-jira/ 供参考
• 更新至MCP SDK v1.23.0 registerTool API
• 已修复已弃用的问题 /rest/api/3/search 端点（现在使用 /rest/api/3/search/jql)
• 将所有依赖项更新为最新版本（Zod v4.1.13，Commander v14.0.2）

需求

• Node.js：18.0.0或更高
• MCP-SDK：v1.23.0（使用现代注册API）
• Jira：仅限云（不支持服务器/数据中心）

建筑

此服务器遵循5层MCP架构：

1. CLI层 -使用Commander.js的人机界面
2. 工具层 -带有Zod验证的AI接口
3. 控制器层 -业务逻辑和编排
4. 服务层 -直接Jira REST API调用
5. Utils图层 -跨领域问题（记录、格式化、传输）

调试

通过设置启用调试日志记录 DEBUG 环境变量：

# In Claude Desktop config
{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-jira"],
      "env": {
        "DEBUG": "true",
        "ATLASSIAN_SITE_NAME": "your-company",
        "ATLASSIAN_USER_EMAIL": "your.email@company.com",
        "ATLASSIAN_API_TOKEN": "your_api_token"
      }
    }
  }
}

调试日志将写入 ~/.mcp/data/mcp-server-atlassian-jira..log

检查原始API响应： 当响应被截断时，完整的原始响应将保存到 /tmp/mcp/mcp-server-atlassian-jira/-.txt 包含请求/响应的详细信息。

从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

v3.0+的优点：

• 完全访问任何Jira REST API v3端点（不仅仅是预定义的工具）
• JMESPath过滤实现高效数据提取
• 跨所有HTTP方法的一致接口
• TOON格式可节省30-60%的代币
• 使用原始文件日志记录自动截断响应

支持

需要帮助？以下是如何获得帮助：

1. 检查上面的故障排除部分 -其中涵盖了最常见的问题
2. 访问我们的GitHub仓库 有关文档和示例：
3. 报告问题 在
4. 开始讨论 用于功能请求或一般问题

______________________________________________________________________

*为希望将人工智能引入项目管理工作流程的团队精心制作。*