Jira MCP Server

什么是 Jira MCP Server？

Jira MCP Server（@aashari/mcp-server-atlassian-jira）是一个社区维护的 jira mcp server，通过五个可调用任意 Jira REST API v3 端点的通用工具，把 Claude、Cursor 和其他 MCP 客户端连接到 Jira Cloud。

它是由 aashari 开发的开源 Node.js/TypeScript 项目，并非 Atlassian 官方产品。它在本地通过 stdio 运行，使用你自己的 Atlassian 邮箱和 API token，让 AI 助手可以用 JQL 搜索 issue、读取 issue 和评论、创建或更新 issue、记录工时，并推动 issue 完成工作流流转。同一个包还可以作为命令行工具使用。

如何使用 Jira MCP Server？

你需要 Node.js 18 或更高版本，以及一个 Jira Cloud 站点（your-company.atlassian.net）。不支持 Jira Server 和 Data Center。

1. 在 Atlassian API Tokens 页面创建 API token：点击 Create API token，填写名称，并立即复制 token。
2. 设置三个值：ATLASSIAN_SITE_NAME（子域名，例如 your-company）、ATLASSIAN_USER_EMAIL 和 ATLASSIAN_API_TOKEN。
3. 在接入客户端之前，先在终端里测试：

export ATLASSIAN_SITE_NAME="your-company"
export ATLASSIAN_USER_EMAIL="your.email@company.com"
export ATLASSIAN_API_TOKEN="your_api_token"

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

Claude Desktop

把服务器添加到 claude_desktop_config.json，然后重启 Claude Desktop：

{
  "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 Code

用 Claude Code CLI 注册同样的 stdio 命令：

claude mcp add jira \
  -e ATLASSIAN_SITE_NAME=your-company \
  -e ATLASSIAN_USER_EMAIL=your.email@company.com \
  -e ATLASSIAN_API_TOKEN=your_api_token \
  -- npx -y @aashari/mcp-server-atlassian-jira

Cursor 及其他客户端

任何支持 stdio MCP 服务器的客户端都可以使用上面的 mcpServers 配置块（在 Cursor 中，把它放进 MCP 配置文件）。你也可以用 npm install -g @aashari/mcp-server-atlassian-jira 全局安装。

如果不想在每个客户端里重复填写凭据，可以把它们统一保存在 ~/.mcp/configs.json 中：

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

除 "jira" 外，也可以使用 "atlassian-jira"、"@aashari/mcp-server-atlassian-jira" 或 "mcp-server-atlassian-jira" 作为键名。

Jira MCP Server 的主要功能

• 五个通用工具（jira_get、jira_post、jira_put、jira_patch、jira_delete），可以访问任意 Jira Cloud REST API v3 端点，而不是一组固定操作。
• 默认使用 TOON（Token-Oriented Object Notation）输出格式，README 称与 JSON 相比可减少 30–60% 的 token 消耗；也可以通过 --output-format json 或 outputFormat: "json" 使用 JSON。
• 支持 JMESPath 过滤（--jq），只返回你需要的字段，例如 key、summary 和 status。
• 超过约 40k 字符的响应会被自动截断，完整的原始响应保存在 /tmp/mcp/mcp-server-atlassian-jira/ 下。
• CLI 与每个 MCP 工具一一对应（get、post、put、patch、delete），方便写脚本和快速检查。
• 使用你自己的凭据在本地运行，不经过任何第三方服务。
• 通过 DEBUG=true 开启调试日志，日志写入 ~/.mcp/data/。

Jira MCP Server 工具

从第 3 版开始，旧的按任务划分的工具（如 jira_ls_projects 和 jira_get_issue）被替换为每种 HTTP 方法一个工具：

• 读取： jira_get 覆盖项目（/rest/api/3/project/search）、issue 详情（/rest/api/3/issue/{key}）、JQL 搜索（/rest/api/3/search/jql，带 jql 参数）、评论、工时记录、状态、issue 类型、优先级和用户。
• 创建： jira_post 用于创建 issue（/rest/api/3/issue）、添加评论和工时记录，以及执行工作流流转。
• 更新： jira_put 用于整体替换，jira_patch 用于部分更新，例如 issue 字段。
• 删除： jira_delete 用于删除评论、工时记录等资源。

由于工具是通用的，助手需要知道正确的 API 路径。README 列出了常用路径，并指出 /rest/api/3/search 已被弃用，应改用 /rest/api/3/search/jql。

Jira MCP Server 的使用场景

• 站会准备："Show me details about PROJ-123 including comments."
• 个人任务梳理："List all high priority issues assigned to me that are in progress."
• 用 JQL 跨项目搜索："Find all bugs in progress across my projects."
• 在编辑器里创建 issue：一边看出错的代码，一边说"Create a new bug in the MOBILE project"。
• 更新进度："Add a comment to PROJ-456: 'Code review completed, ready for testing.'"
• 工时与工作流：不打开 Jira 就能记录工时，或把 issue 推进到下一个流转状态。

Jira MCP Server 与替代方案对比

• Atlassian Rovo MCP Server（官方）：Atlassian 自己托管的远程服务器，覆盖 Jira、Confluence 及其他 Atlassian Cloud 应用，支持 OAuth 2.1 或 API token 登录。如果你需要厂商支持的托管方案，可以选择它；参见 Atlassian Rovo MCP 文档。
• Atlassian MCP Server (Jira & Confluence)：一个社区服务器，同时覆盖 Jira 和 Confluence，并为两者分别提供专用工具。
• 本 Jira MCP 服务器：一个小巧、本地运行、只针对 Jira 的 atlassian jira mcp 方案。五个通用工具让工具列表保持精简，同时可以访问完整的 REST API，但模型需要知道该调用哪个端点。

Jira MCP Server 常见问题排查

• "Authentication failed" 或 403 Forbidden：检查 API token 是否仍然有效，并确认 ATLASSIAN_SITE_NAME 只填写子域名（mycompany，而不是完整 URL）。可用 npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/myself" 测试。
• 404 / 找不到资源：API 路径区分大小写；请使用项目 key（DEV）而不是项目名称，并使用完整的 issue key（DEV-123）。确认你能在浏览器中打开该项目。
• 搜索没有结果：先在 Jira 的高级搜索中验证 JQL，并使用 /rest/api/3/search/jql 而不是已弃用的 /rest/api/3/search。
• Claude Desktop 中看不到服务器：修改配置文件后重启 Claude Desktop，并确认你编辑的是当前操作系统对应的配置文件。
• 响应被截断：大响应会按设计被截断。用 --jq 或 JQL 缩小请求范围，或者查看 /tmp/mcp/mcp-server-atlassian-jira/ 下保存的原始文件。