Atlassian Jira MCP Server

将 AI 连接到你的 Jira 项目

将 Claude、Cursor AI 和其他 AI 助手直接连接到你的 Jira 项目、问题和工作流，彻底改变你管理和跟踪工作的方式。即时获取项目洞察，简化问题管理，并增强团队协作。

你可以做什么

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

非常适合

• 开发者，需要快速查看问题详情和开发上下文
• 项目经理，跟踪进度、优先级和团队任务分配
• Scrum Master，管理冲刺和工作流状态
• 团队负责人，监控项目健康状况和问题解决情况
• QA 工程师，跟踪错误和测试状态
• 任何人，希望使用自然语言与 Jira 交互

快速开始

只需 2 分钟即可开始使用：

1. 获取 Jira 凭据

生成 Jira API 令牌：

1. 前往 Atlassian 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="[email protected]"
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 Desktop 用户

将以下内容添加到你的 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": "[email protected]",
        "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": "[email protected]",
      "ATLASSIAN_API_TOKEN": "your_api_token"
    }
  }
}

**可选配置键：**系统也接受 "atlassian-jira"、"@aashari/mcp-server-atlassian-jira" 或 "mcp-server-atlassian-jira"，用来替代 "jira"。

可用工具

此 MCP 服务提供 5 个通用工具，可访问任意 Jira API 端点：

工具	说明
jira_get	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 - 列出所有项目（不分页，旧版）
• /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 使用表格数组和精简语法，非常适合 AI 使用。

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

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/<timestamp>-<random>.txt，供参考。

截断时，你会看到：

• 截断通知及原始文件路径
• 使用更合适的筛选条件优化查询的建议
• 已显示数据占总数据量的百分比

实际示例

浏览你的项目

向 AI 助手提问：

• “列出我有权访问的所有项目”
• “向我展示 DEV 项目的详细信息”
• “哪些项目名称中包含单词 ‘Platform’？”

搜索和跟踪问题

向 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 Forbidden”

1. 检查你的 API Token 权限：

   • 前往 Atlassian API Tokens
   • 确认你的 Token 仍处于有效状态且尚未过期

2. 确认站点名称格式：

   • 如果你的 Jira URL 是 https://mycompany.atlassian.net
   • 站点名称应仅为 mycompany

3. 测试你的凭据：

   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 Desktop 集成问题

1. 更新配置文件后，重启 Claude Desktop
2. 确认配置文件位置：
   • macOS：~/.claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

获取帮助

如果问题仍未解决：

1. 运行一条简单的测试命令，确认一切正常
2. 在 GitHub Issues 中查找类似问题
3. 创建一个新问题，并附上错误消息和设置信息

常见问题

我需要哪些权限？

你的 Atlassian 账户需要：

• Jira 访问权限，以及查询目标项目所需的相应权限
• 具有适当权限的 API Token（创建 Token 时会自动授予）

我可以将它用于 Jira Server（本地部署）吗？

目前，此工具仅支持 Jira Cloud。未来版本可能会添加对 Jira Server/Data Center 的支持。

如何查找站点名称？

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

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

此工具适用于哪些 AI 助手？

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

• Claude Desktop
• Cursor 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：仅支持 Cloud（不支持 Server/Data Center）

架构

此服务遵循 5 层 MCP 架构：

1. CLI 层 - 使用 Commander.js 提供人机交互界面
2. 工具层 - 使用 Zod 验证提供 AI 接口
3. 控制器层 - 处理业务逻辑和编排
4. 服务层 - 直接调用 Jira REST API
5. 工具库层 - 处理横切关注点（日志记录、格式化、传输）

调试

设置 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": "[email protected]",
        "ATLASSIAN_API_TOKEN": "your_api_token"
      }
    }
  }
}

调试日志会写入 ~/.mcp/data/mcp-server-atlassian-jira.<session-id>.log

查看原始 API 响应： 截断响应时，完整的原始响应会连同请求/响应详情一起保存到 /tmp/mcp/mcp-server-atlassian-jira/<timestamp>-<random>.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 仓库，查看文档和示例：github.com/aashari/mcp-server-atlassian-jira
3. 在 GitHub Issues 报告问题
4. 发起讨论，提出功能请求或一般问题

---

用心打造，献给希望将 AI 引入项目管理工作流的团队。