jira-easy-mcp

jira-easy-mcp

又一个用于 Jira 的模型上下文协议（MCP）服务，无需身份验证令牌。提供全面的 Jira 自动化工具，包括问题、项目、看板、冲刺、评论、工作日志等。

测试环境： Jira Server / Data Center 7.13、8.20、9.12 和 10.3（已自动测试所有工具，参见开发与测试）

---

🔑 为什么选择这个 MCP？

支持基本身份验证（用户名 + 密码）——无需 API 令牌！

大多数 Jira MCP 服务都需要 OAuth 或 API 令牌，而许多组织会限制或禁止使用这些令牌。本 MCP 使用 HTTP 基本身份验证，因此只需 Jira 用户名和密码即可连接。适用于：

• 🏢 禁止管理员创建 API 令牌的企业环境
• 🔒 未配置 OAuth 的自托管 Jira Server 实例
• ⚡ 无需经过 IT 审批流程即可快速设置

---

快速开始

VS Code（工作区配置）

在工作区根目录中创建 .vscode/mcp.json：

{
  "servers": {
    "jira": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "jira-easy-mcp"],
      "env": {
        "JIRA_BASE_URL": "https://your-jira-instance.com",
        "JIRA_USERNAME": "your-username",
        "JIRA_PASSWORD": "your-password",
        "JIRA_PROJECTS_FILTER": "ABC,DEF,XYZ",
        "JIRA_RESPONSE_FORMAT": "JSON"
      }
    }
  }
}

添加到 VS Code 设置中，即可在所有工作区访问。

注意： JIRA_PROJECTS_FILTER 和 JIRA_RESPONSE_FORMAT 为可选项。项目筛选器会将访问范围限制为指定项目。响应格式可以是 JSON（默认）或 TOON（面向文本的表示法）。

Claude Code

claude mcp add jira \
  -e JIRA_BASE_URL=https://your-jira-instance.com \
  -e JIRA_USERNAME=your-username \
  -e JIRA_PASSWORD=your-password \
  -- npx -y jira-easy-mcp

Codex CLI

添加到 ~/.codex/config.toml：

[mcp_servers.jira]
command = "npx"
args = ["-y", "jira-easy-mcp"]
env = { JIRA_BASE_URL = "https://your-jira-instance.com", JIRA_USERNAME = "your-username", JIRA_PASSWORD = "your-password" }

其他客户端

Cursor： ~/.cursor/mcp.json 或 .cursor/mcp.json（使用 "mcpServers": { ... } 包装）
Windsurf： 添加到 Windsurf MCP 设置中（使用 "mcpServers": { ... } 包装）
Claude Desktop： 编辑 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\；使用 "mcpServers": { ... } 包装）
Gemini CLI： ~/.gemini/settings.json（使用 "mcpServers": { ... } 包装）

这些客户端均使用与上方 VS Code 配置相同的 command、args 和 env 配置。

**Windows：**如果客户端无法启动 npx，请使用 "command": "cmd"，并设置 "args": ["/c", "npx", "-y", "jira-easy-mcp"]。

**工具数量限制：**部分客户端（尤其是 Cursor）会限制发送给模型的工具数量，历史上通常限制为所有服务合计约 40 个。本服务有 41 个工具；请在客户端的 MCP 设置中关闭不需要的工具。

使用操作系统钥匙串中的凭据（可选）

如需避免将密码写入配置文件，请省略 JIRA_USERNAME/JIRA_PASSWORD，并在服务名称 JiraMCP 下存储凭据：

• macOS：security add-generic-password -s JiraMCP -a your-username -w（会提示输入密码；首次启动时，macOS 会询问是否允许 node 读取密码）
• Windows：cmdkey /generic:JiraMCP /user:your-username /pass（使用 /generic，而非 /add）

如果存储了多个账户，请设置 JIRA_USERNAME 以选择其中一个。如果同时设置了 JIRA_USERNAME 和 JIRA_PASSWORD，则会使用这两个变量，且不会读取钥匙串。钥匙串支持依赖可选的 keytar 软件包；如果无法在你的计算机上安装，请使用环境变量。

---

常见用例

任务	工具	示例提示词
搜索问题	jira_search	"搜索项目 ABC 中分配给我的所有未解决 Bug"
获取问题详情	jira_get_issue	"显示问题 ABC-123 的详情"
查看问题图片	jira_get_issue_images	"显示附加到 ABC-123 的截图"
上传附件	jira_upload_attachment	"将 /Users/me/Desktop/error.png 附加到 ABC-123"
创建问题	jira_create_issue	"在项目 ABC 中创建一个标题为 'Login button not working' 的新 Bug"
更新问题	jira_update_issue	"将 ABC-123 的优先级改为 High，并分配给 john.doe"
编辑自定义字段	jira_update_issue + jira_get_edit_meta	"将 ABC-123 的 Severity 设为 Critical"（唯一名称或 customfield_ ID）
添加评论	jira_add_comment	"向 ABC-123 添加评论：'Fix deployed to staging'"
更改状态	jira_transition_issue	"将 ABC-123 移至 Done"
记录工时	jira_add_worklog	"为昨天在 ABC-123 上记录 2 小时工时"
列出项目	jira_get_projects	"显示我有权访问的所有项目"
查看冲刺	jira_get_sprints	"项目 ABC 当前冲刺中有哪些内容？"
关联问题	jira_create_link	"将 ABC-123 关联为阻止 ABC-124 的问题"
生成筛选器 URL	jira_generate_filter_url	"为过去 7 天内更新的所有未解决 Bug 创建可分享链接"

---

使用 MCP Inspector 测试

MCP Inspector 提供了一个 Web UI，可用于交互式测试所有工具：

npx @modelcontextprotocol/inspector npx jira-easy-mcp

这会在浏览器中打开 http://localhost:6274，你可以在其中：

• 查看所有可用工具
• 使用自定义参数测试每个工具
• 查看原始 JSON 响应

注意： 连接前，请在 Inspector UI 中填写以下值：JIRA_BASE_URL、JIRA_USERNAME、JIRA_PASSWORD。

---

自定义字段

Jira REST API v2 使用 ID 标识自定义字段（customfield_10006）。字段值是该字段类型对应的原始 REST 负载。显示名称仅在相关屏幕上唯一时才可用（精确匹配，区分大小写）。

读取（jira_get_issue）

默认响应包含系统字段，以及当前有值的自定义字段，每项格式为 { "id", "name", "value" }。除非传入 include: ["comments"]（和／或 worklogs、attachments），否则不包含评论、工时记录和附件。除非设置 customFields: "all" 或传入 fields，否则会省略值为 null 的自定义字段。

fields 可缩小自定义字段 GET 的范围（ID 如 customfield_11205，或编辑屏幕上唯一的名称，如 Severity）。即使请求的字段值为 null，也会返回该字段。名称取自此问题的 expand=names，而非 GET /field。

{
  "key": "ABC-123",
  "customFields": [
    { "id": "customfield_10006", "name": "Story Points", "value": 5 },
    { "id": "customfield_10107", "name": "Flagged", "value": { "value": "Yes" } }
  ]
}

写入（jira_update_issue / jira_create_issue）

传入以 ID（customfield_10006）或 jira_get_edit_meta / jira_get_create_meta 返回的唯一名称为键的 customFields。ID 无需额外 GET。名称会根据对应问题类型的 meta 解析；若名称重复，则会安全地拒绝操作（请使用 ID）。不要在每次写入前调用 jira_get_fields。

Schema type	REST 值
string / number / date	"text"、5、"2011-10-03"
option（选择项）	{ "value": "Yes" } 或 { "id": "10100" }
user（Server）	{ "name": "username" } — 不能使用 Cloud 的 accountId
选项数组	[{ "value": "A" }, { "value": "B" }]（itemsType: option）
清除	null

如果 jira_get_fields 列出的字段未出现在 edit/create meta 中，则该字段不在对应屏幕上，无法更新。

搜索（jira_search）

默认搜索仅返回系统字段（不包含自定义字段、评论／工时记录／附件详情）。fields 用于额外添加字段：系统键和 customfield_ ID 会直接传递；显示名称则通过实时、未缓存的 GET /field 解析。优先使用 ID。名称有歧义时会安全地拒绝操作。

目录（jira_get_fields）

用于获取 JQL 子句名称，不要将其作为每次创建或更新前的必经步骤。对于某个问题类型的字段，请使用 jira_get_edit_meta 或 jira_get_create_meta。

---

可选环境变量

变量	默认值	说明
JIRA_PROJECTS_FILTER	(无)	逗号分隔的项目键。工具会拒绝列表之外的问题键／项目键（问题 ID 必须以键的形式提供），并将 JQL 限定在这些项目中。不会检查看板、冲刺和链接 ID
JIRA_RESPONSE_FORMAT	JSON	响应格式：JSON 或 TOON
JIRA_LOG_LEVEL	INFO	日志详细程度：DEBUG、INFO、WARN、ERROR
JIRA_TIMEOUT	30000	请求超时时间，单位为毫秒
JIRA_RETRY_COUNT	3	超时、429 和 502-504 时的重试次数。写入请求（POST）仅在遇到 429 时重试，避免 Jira 响应缓慢时重复创建问题、评论或链接
JIRA_RETRY_DELAY	1000	重试间隔基数（毫秒）
JIRA_SSL_VERIFY	true	设置为 false 可跳过 SSL 验证。使用公司 CA 时，建议设置 NODE_EXTRA_CA_CERTS=/path/to/ca.pem
JIRA_CACHE_TTL	300	静态数据的缓存 TTL，单位为秒

jira_get_issue_images 通过 Jira 的身份验证附件 URL （/secure/attachment/...，Jira Server/Data Center）下载图像。默认最多返回五张图像 （最多十张），每张图像大小上限为 10 MiB，每次响应大小上限为 20 MiB。 jira_upload_attachment 会从运行服务的机器上，根据绝对路径读取本地文件。

---

故障排除

错误	解决方法
Authentication failed ... restart the MCP server	凭据错误。首次失败后，服务会停止登录，因此 Agent 反复重试也不会触发 Jira 的 CAPTCHA 锁定。修正凭据并重启服务（或在客户端中重新加载 MCP 服务）。
Login blocked by CAPTCHA	登录失败次数过多。先在浏览器中登录 Jira 一次，然后重试。
Jira redirected to ...	JIRA_BASE_URL 配置有误：如果 Jira 重定向到 https://，请使用 https://；或者添加上下文路径。重定向到登录页面表示 Jira 前面有一个 SSO 代理。
No Jira REST API at ...	通常是缺少上下文路径，例如应使用 https://host/jira，而不是 https://host。
fetch failed / 证书错误	公司 CA：使用 NODE_EXTRA_CA_CERTS=/path/to/ca.pem 启动服务。最后的办法：设置 JIRA_SSL_VERIFY=false。
... outside the allowed projects	此键不在 JIRA_PROJECTS_FILTER 中。

---

开发与测试

pnpm install
pnpm test              # unit tests + build (any OS, Node 18+)
node scripts/smoke.mjs # MCP handshake check (needs JIRA_BASE_URL set to anything)

针对真实 Jira（Docker、Node 20.10+）：此辅助程序会启动一个临时 Jira，使用 Atlassian 公开的3 小时时限测试许可证完成设置， 并创建一个管理员（admin / Jira-IT-admin-1）、一个第二用户和两个 Scrum 项目（IT、OT）。

pnpm jira:up 9.12 8080            # or 7.13, 8.20, 10.3 (Jira 10 also starts PostgreSQL)
JIRA_IT_BASE_URL=http://localhost:8080 pnpm test:integration
pnpm jira:down 9.12

pnpm jira:up 9.12 8080 /jira 会在上下文路径下提供 Jira 服务。每个实例需要约 3 GB 的 Docker 内存；在资源有限的机器上请一次只运行一个实例。仅当 keytar 可用且不存在真实的 JiraMCP 凭据时，才会运行钥匙串测试；这些测试会删除其创建的内容。 CI 会在 Linux、macOS 和 Windows（Node 18-24）上运行单元测试，并针对以上每个版本运行集成测试。

---

兼容性

Jira 版本	状态
Jira Server 7.12.1 / 7.12.3	✅ 已手动测试
Jira Server 7.13	✅ 已自动化（所有工具）
Jira Server / DC 8.20	✅ 已自动化（所有工具）
Jira DC 9.12（也支持 /jira 上下文路径）	✅ 已自动化（所有工具）
Jira DC 10.3	✅ 已自动化（所有工具）
Jira Cloud	︖ 未测试（请使用官方 MCP）

需要 Node.js 18+。CI 会在 macOS、Linux 和 Windows（Node.js 18–24）上运行单元测试和 MCP 冒烟测试。

你可以通过报告问题来改进此项目。