jira-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@jira-mcp list my open issues assigned to me"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@mohou/jira-mcp
自托管 Jira Server / Data Center 的 MCP server。为一个具体约束而做:Jira 8.5.7 没有 Personal Access Token(PAT 从 8.14 才有),所以认证必须走 Basic Auth;而实例上插件多、自定义字段多,固定工具面覆盖不了。
跑起来是一个进程、一个 MCP server、109 个工具:
55 jira_* 核心实体(issue / comment / worklog / attachment / project / user
/ link / watcher / meta / agile)
54 zephyr * Zephyr Scale(测试用例 / 文件夹 / 测试循环 / 执行 / 测试计划 / 附件 / 自动化结果)Node >= 22.6关于构建:从 GitHub 克隆下来不需要构建 —— 源码直接跑(Node 原生类型擦除)。但从 npm 装下来的包带的是
dist/jira-server.mjs单文件 bundle:Node 不允许擦除node_modules里.ts的类型 (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING),所以发布物必须是编译后的 JS。bin/jira-server.mjs按磁盘上有什么来选:有src/就用源码(检出目录绝不会跑到过期的构建产物),否则用 bundle。
从 npm 安装
npx @mohou/jira-mcp # 或 npm i -g @mohou/jira-mcp{
"mcpServers": {
"jira": {
"command": "npx",
"args": ["-y", "@mohou/jira-mcp"],
"env": {
"JIRA_BASE_URL": "https://jira.corp.com",
"JIRA_USERNAME": "your.name",
"JIRA_PASSWORD": "***",
"ZEPHYR_ALLOW_INTERNAL_API": "true"
}
}
}
}Related MCP server: jiradatacenter-mcp
从源码运行
npm install
JIRA_BASE_URL=https://jira.corp.com \
JIRA_USERNAME=your.name JIRA_PASSWORD='***' \
ZEPHYR_ALLOW_INTERNAL_API=true \
npm start入口是 bin/jira-server.mjs(纯 JS 的版本守卫):Node 低于 22.6 会直接给出可读报错,而不是从 TypeScript 里抛一个语法错误。
接入任意 MCP 客户端:
{
"mcpServers": {
"jira": {
"command": "/absolute/path/to/node",
"args": ["/absolute/path/to/jira-mcp/bin/jira-server.mjs"],
"env": {
"JIRA_BASE_URL": "https://jira.corp.com",
"JIRA_USERNAME": "your.name",
"JIRA_PASSWORD": "***",
"ZEPHYR_ALLOW_INTERNAL_API": "true"
}
}
}
}环境变量
变量 | 默认 | 说明 |
| — | 必填 |
| — | 8.5.7 走这条(Basic Auth) |
| — | 8.14+ 才可用;设了就用 Bearer |
| 按上面的变量推断 |
|
|
| 统一只读开关,同时约束核心工具和 Zephyr |
|
| 自签证书设 |
|
| 单次请求超时 |
|
| 对 429/502/503/504 与网络错误的重试次数(尊重 |
|
| 别名文件路径,可指向外部 |
|
|
|
|
| 开启后多 12 个工具(见下) |
| — | Zephyr 工具的默认项目 |
错误信息是可执行的
失败的返回不是裸状态码,而是带着下一步动作:
400 Field 'customfield_20001' cannot be set. It is not on the appropriate screen...
→ 字段 'customfield_20001' 不在该项目/类型的 Screen 上,或字段名不存在。
先用 jira_describe_create / jira_describe_edit 查看当前真正可填的字段。
401 → 认证失败。若该账号走 SSO/Crowd 且无本地密码,或实例开启了 CAPTCHA,Basic Auth 不可用。
404(插件路径) → 路径不存在。若这是插件接口,先确认插件已安装(可调 jira_list_plugins)。为什么这样设计
1. 字段知识是运行时数据,不是代码
customfield_20001 在你们实例里是"部门"、值是 {"id":"10101"},在别人实例里是别的字段。把它写进代码就锁死了 —— 这正是大多数现成 MCP server 的死法。
所以写接口一律 fields 原样透传,字段的形状由两个"填空题"工具在运行时从 Jira 读出来:
jira_describe_create(project, type) → 创建时可填的字段 + 取值形态 + 可选值 + 必填性
jira_describe_edit(issueKey) → 这个 issue 当前能改什么(已按工作流/屏幕过滤)模型看到的实际输出:
项目 PROJ / 类型 Task — 创建时可填 可填 5 个字段(必填 2)
必填:
summary string → "文本"
customfield_20001(部门) option → {"id":"..."} 可选项: 平台组(10101) | 基础架构组(10102)
选填:
assignee user → {"name":"username"} 可选项: alice(alice)
customfield_20002(上线日期) date → "2026-01-01"
按上面的形态填好后调用: jira_create_issue({ fields: {...} })写不进去的字段(attachment、issuelink 等)会被过滤掉,模型不用撞 400。管理员改字段、插件加字段,模板自动跟随,零代码改动。
2. 三层各管一件事,互不越界
层 | 管什么 | 例子 |
| 参数的形状和用法 |
|
| 有哪些工具、打哪个端点 | Tempo 的 |
Jira meta 接口 | 字段有哪些、值怎么填 |
|
types.ts 里的 .describe() 直接进模型看到的 JSON Schema,所以"Server 用 name"这类坑写一次,所有引用它的工具都自动获得正确提示。
3. 入参有类型,返回值也有
入参侧是 src/types.ts 的 T,返回值侧是对称的 src/entity-types.ts 的 E —— issue、comment、worklog、attachment、project、user、serverInfo、paged,以及 testCase / testRun / testResult。
jira_get_issue: defineTool({
readOnly: true, returns: E.issue, // ← 声明后成为 MCP outputSchema,并返回 structuredContent
input: { key: T.issueKey, fields: T.fieldIds.optional() },
run: ({ key, fields }) => jira('GET', `/issue/${key}`, { query: { fields: fields?.join(',') ?? '*all' } }),
}),只声明信封,不声明业务字段。 Jira 的响应字段随实例、插件、版本变化,所以实体类型用 .passthrough() 并只固定稳定部分(id / key / 数组字段名):
// jira_get_issue 的 outputSchema(模型实际看到的)
{ "type": "object", "required": ["id", "key", "fields"],
"properties": { "id": {...}, "key": {...}, "fields": {"description": "...customfield_xxxxx..."} },
"additionalProperties": true } // ← 未声明的字段必须放行两条硬约束(踩过才知道):
约束 | 原因 |
204 类工具不声明 | update/delete/assign/transition 返回空响应,而声明了 outputSchema 就必须给 structuredContent —— 空 body 会让 MCP 结果校验直接失败 |
数组根的工具不声明 | MCP 要求 outputSchema 的对象根; |
当前 109 个工具里 25 个带 outputSchema(我们的核心工具)。Zephyr 的 54 个来自 vendored 上游代码,自带 zod 校验与契约测试,其返回形状随实例变化,所以只在 E 里登记信封、不强加到上游工具上。
4. 8.5.7 兼容性有测试守着
Server 8.5.7 只有 REST API v2(加 Agile 1.0),/rest/api/3 在它上面不存在。test/compat.test.mjs 三道断言守住这条:
src/里没有任何文件引用/rest/api/3tools.d/*.json里没有跑一遍全部工具(读 + 写),断言 mock 收到的每一个请求路径都落在
/rest/api/2/、/rest/agile/1.0/或已声明的插件前缀里
第 3 条上线当天就抓出了一个真 bug:附件上传绕过了路径解析,POST 到了 /issue/... 而不是 /rest/api/2/issue/...。
扩展
加一个工具(代码)
// src/entities/worklog.ts
jira_list_worklogs: defineTool({
readOnly: true, desc: '列 issue 工时',
input: { key: T.issueKey },
run: ({ key }) => jira('GET', `/issue/${key}/worklog`),
}),run 返回对象 → 自动 JSON 化;返回字符串 → 原样给模型;抛异常 → 变成 isError。没有别的约定。
加一个实体
新建 src/entities/xxx.ts 导出一个普通对象,在 src/entities/index.ts 数组合里加一行。
加一个插件(JSON,不用改代码)
// tools.d/plugins.json
"jira_tempo_worklogs": {
"desc": "查 Tempo 工时",
"readOnly": true,
"params": { "from": "string", "to": "string", "projectKey": "projectKey" }, // ← 引用类型注册表
"required": ["from", "to"],
"method": "GET",
"path": "/rest/tempo-timesheets/4/worklogs",
"query": { "from": "{from}", "to": "{to}" }
}"{x}" 整串占位 → 原样传值(保留类型);"a{x}b" → 字符串插值。JSON 里定义的工具会覆盖代码里的同名工具(后覆盖前)。
声明还支持 returns:引用 src/entity-types.ts 里的实体名(例如 "returns": "paged"),声明后 JSON 工具也会带 outputSchema 并返回 structuredContent——和代码里声明的工具完全一致。形状未知时用 anyObject(MCP 要求对象根,这是最宽松且诚实的声明)。
完整的 DSL 参考、校验规则、以及"怎么找到插件的 REST 路径"写在 tools.d/README.md;tools.d/examples/ 里有可复制的模板(该目录不会被自动加载,有测试守着)。
不确定插件端点时,先探一遍(只发 GET,不写任何数据):
JIRA_BASE_URL=... JIRA_USERNAME=... JIRA_PASSWORD=... npm run probe:paths
# 或指定路径:
JIRA_BASE_URL=... ... node scripts/probe-paths.mjs /rest/myplugin/1.0/thing它对 Tempo / ScriptRunner / JSM / Zephyr Scale / Xray / Zephyr Squad / Structure / Insight 的常见路径逐个报告状态码:404 是没有,405 是路径存在但方法不对(脚本会自动补一次 POST),200 是可用的。把输出贴回来就能把可用的那些写成 tools.d/ 声明。
加一个类型
在 src/types.ts 的 T 里加一项,代码和 JSON 立刻都能引用。
逃生口
装了没适配的插件,直接打它的 REST:
jira_request({ method: 'POST', path: '/rest/scriptrunner/latest/custom/foo', body: {...} })/rest/ 开头的路径原样透传,不会被拼成 /rest/api/2/rest/...。
Zephyr Scale
Zephyr 是 vendored 进来的(不是依赖 npm 包),代码在 src/entities/zephyr/,注册到同一个 server。见 NOTICE.md。
默认 42 个工具;
ZEPHYR_ALLOW_INTERNAL_API=true再挂 12 个(/rest/tests/1.0内部 API)覆盖测试用例、文件夹、测试循环、执行结果、测试计划、附件、自动化/Cucumber 结果导入、BDD feature 导出
为什么不用 JSON 声明 Zephyr:它的关键操作不是"一次 REST 调用" ——
测试循环不可变(要建新循环再搬结果)、测试步骤要按 id 读-合并-写(否则静默丢步骤)、状态名大小写敏感且公开 API 不暴露、executedBy 要 Jira user key 而不是用户名。用 JSON 只能写出一个看起来完整、实际会静默失败的子集。
测试
npm run tools:describe # 列出每个工具的输入/输出 schema 结构;--json 看完整 schema,用于检查插件声明
npm test # 离线契约 + 传输层测试(mock Jira,无网络)
npm run verify:vendor # 用上游 Zephyr 自己的测试套件验证 vendoring 没改坏行为
npm run verify:live # 对真实实例逐工具验证
npm run probe:paths # 探测候选插件端点
npm run capture:instance # 抓取真实实例的完整层级结构,用于扩展 schemanpm test 里有一条不变量测试(test/descriptions.test.mjs):任何工具、任何入参、任何输出字段缺 description,或 schema 里出现 $ref,都会失败。这不是洁癖 —— $ref 在不解析它的客户端里等于"没有类型",而模型的工具调用全靠这些描述。
verify:vendor 从上游 pinned commit 拉干净源码,换成我们的 vendored 版本跑它的测试套件。当前结果 17 个测试文件全绿、1175 个用例通过、0 失败(跳过 2 个依赖未 vendoring 的打包文件)。详见 NOTICE.md。
verify:live 默认只调用只读工具(readOnlyHint=true),不产生任何写入,可以安全地对生产实例跑:
JIRA_BASE_URL=https://jira.corp.com JIRA_USERNAME=... JIRA_PASSWORD=... \
ZEPHYR_ALLOW_INTERNAL_API=true npm run verify:live它会先探测版本和连通性,然后自动发现真实取值(项目 key、issue key、board id、sprint id),再逐个验证只读工具,最后写出 verify-report.md。
写操作验证是可选的,而且要过两道闸(test/verify-writes.mjs):
VERIFY_WRITE=1 VERIFY_PROJECT=PROJ \
JIRA_BASE_URL=... JIRA_USERNAME=... JIRA_PASSWORD=... npm run verify:live必须同时给
VERIFY_PROJECT,没有默认值 —— 打错字不会写到别的项目去全部操作发生在一个新建的探针 issue 上,最后在
finally里删掉:创建/更新/指派、评论增改删、工时加删、watcher 加删、附件上传删除、remote link 创建、状态流转唯一触及外部对象的动作是 link 到已有 issue,随后立即删除该 link(那个 issue 本身不被修改)
当前对 mock 的端到端结果:39 通过 / 0 失败 / 15 跳过(只读)+ 写阶段 25 步全通。
"跳过"通常是插件没装或需要真实测试数据,不代表实现有问题。 运行前会先做一轮发现:当前用户、项目、issue、附件 id、JSM 服务台 id、Zephyr 的用例/循环/计划 key、board、sprint。这些 id 决定了有多少工具能被真正验证——发现逻辑抽在 test/discover.mjs 里并有独立测试,因为一旦它退化,验证覆盖面会静默缩水。
观察 Zephyr 的输出契约
Zephyr 那 54 个工具来自 vendored 上游代码,返回的是文本块里的 JSON(content[0].text),既没有 structuredContent 也没有 outputSchema。想给它们挂 schema,必须先知道每个工具真实返回什么 —— 因为一旦声明了 outputSchema,SDK 就要求每次成功调用都交出匹配的 structuredContent,形状不符会直接抛错(server/mcp.js 里就是 throw new McpError(...)),把一个本来能用的工具变成坏的工具。裸数组返回更是结构上就不可能(必须以对象为根)。
ZEPHYR_OUTPUT_CHECKS=1 是为这件事准备的只观察模式:每次成功调用后,把返回按该工具映射的实体做一次 safeParse,结果写到 stderr。它不改变任何返回值;不设这个变量时包装器根本不安装。
ZEPHYR_OUTPUT_CHECKS=1 npm run verify:live[zephyr-output] ok get_test_case -> E.testCase (object)
[zephyr-output] ok get_custom_field_definitions -> E.customFieldDefinition (array(2 items) all match)
[zephyr-output] MISMATCH some_tool -> E.testResult: id: Expected number, received stringMISMATCH 说明那个映射(或那个实体)不对 —— 在搞清楚之前不要给它挂 outputSchema。映射表在 src/entities/zephyr/output-checks.ts,观察结果同时写进 verify-report.md。
一次运行拿全部结果:加 VERIFY_PROBE_PATHS=1,验证结束后会顺便探测候选插件端点,并把结果写进同一份 verify-report.md:
JIRA_BASE_URL=... JIRA_USERNAME=... JIRA_PASSWORD='***' \
ZEPHYR_ALLOW_INTERNAL_API=true VERIFY_PROBE_PATHS=1 npm run verify:live单独探测也可以(probe:paths 会逐个报告候选路径的状态码:200 可用、405 路径存在但方法不对、404 没有)。候选清单在 test/probe-candidates.mjs,可自行增删。
抓取真实结构以扩展 schema
npm run capture:instance 会走一遍完整层级并保存真实结构,目的是让 src/entity-types.ts 的
schema 有据可依而不是靠猜。它采集:
一个 issue 的全字段(
fields=*all+expand=changelog,renderedFields,names,schema,transitions,editmeta), 以及它的评论、工时、附件、watcher、remote link、流转createmeta/editmeta原始响应 → 哪些字段在创建/编辑屏幕上、是否必填、有哪些可选值多个 issue 的采样(默认 3 条,
CAPTURE_LIMIT可调)→ 字段出现率agile 层级:boards → sprints → sprint issues、backlog
Zephyr 完整层级:test case(+ steps/attachments)→ test run(+ items/results/summary)→ test plan、 文件夹树、状态选项、自定义字段定义、环境
产出三个东西,安全性是刻意分开的:
路径 | 内容 | 能否外传 |
| 键名、类型、数组长度、出现/有值次数。字段值全部抹掉 | ⚠️ 见下 |
| 同样内容的机器可读版 | ✅ |
| 原始 payload,含真实值 | ❌ 已在 |
report.md 里多 issue 采样会让你直接看到该留 required 还是必须 optional:
object
id: string *
key: string *
fields: object *
summary: string *
customfield_20001: object ← 没有 * = 只在 1/2 采样里出现,必须 optional
value: string *
| field | present | value shape |
| `summary` | 2/2 | string |
| `customfield_20001` | 1/2 | object{value} |报告里没有字段值,但有字段名(真机上是业务术语)和采样的标识符(项目 key、issue key、board/sprint id、
Zephyr key)。如果你要把报告公开,加 CAPTURE_REDACT=1,标识符会变成占位符;字段名保留——没有它,字段 id
就没法对应到含义。
* = 该键在每一次采样里都出现(只有一个样本时不会打星,那只代表"只采了一次",不代表不稳定)。
注意报告里有字段名(真机上就是业务术语),值没有。接在 verify:live 后面跑也可以:加 CAPTURE=1。
对 Jira 字段,"出现率"本身没有信息量:每个 issue 都会带回全部字段键,值大多是 null。所以报告
额外统计 filled(非 null、非空的值),这才是"这个自定义字段到底有没有在用"的判据。参考实例上
339 个字段键里只有 37 个有值。
报告会拿真实数据校验 schema(## Schema check 段):每个捕获结果都映射到一个实体,逐个用
src/entity-types.ts 里的 schema 验证。所以 schema 不会悄悄漂移——假设错了就是一条 failed check,
而不是某次工具调用崩掉。改完 schema 可以离线复验,不用再开 VPN:
node scripts/capture-instance.mjs --check capture发布
npm run build # esbuild -> dist/jira-server.mjs(单文件,SDK 与 zod 保持 external)
npm publish # prepack 会自动先 builddist/ 在 .gitignore 里(仓库不留构建产物),但 files 显式包含它,且 prepack 保证每次打包都是新构建。发布前的自检:
rm -rf dist && npm pack # 模拟干净检出,确认 prepack 能构建出 dist
npm i -g ./mohou-jira-mcp-*.tgz # 装到别处,确认真的能起为什么必须构建:Node 对 node_modules 下的 .ts 拒绝类型擦除
(ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING),源码形态装到别人机器上起不来。这是发布物必须带 JS 的唯一原因。
目标实例画像
docs/instance-profile.example.md 是一份示例/模板(全是假数据),演示如何记录实测到的服务器版本、认证方式,以及从自定义字段 schema 反推出的插件清单(UPM 对普通账号不可读)。这份画像是工具面裁剪的依据:例如 jira_tempo_worklogs 被移除,就是因为目标机器上只有 Tempo Planner/Teams/Accounts,没有 Tempo Timesheets。
已知边界
JSON DSL 只能表达单次 REST 调用。需要多步或聚合的逻辑写代码。守住这条,否则会退化成没人会用的 DSL。
Zephyr 的写操作在只读模式下是"注册但调用时拒绝"(上游设计),不是从工具列表里消失。
jira_list_plugins需要管理员权限。实测:非管理员账号访问/rest/plugins/1.0/时,Jira Server 返回 空的 406(它用 HTML 错误页回应Accept: application/json)。工具会依次尝试/rest/plugins/1.0/和/rest/plugins/1.0,失败时给出"需要 Jira 管理员权限"的说明;verify:live把这类失败记为 skip 而不是 fail。tools.d/plugins.json里的插件示例未经真实例验证;tools.d/examples/example-tempo-worklogs.json记录了一个反例:那个端点在真实 8.5.7 上返回 405,启用前必须先确认真实路径。创建/更新受 Jira 的 Screen 配置约束 —— 字段不在对应 Screen 上会 400。这是 Jira 的限制,不是本项目的;
jira_describe_create返回的就是屏幕上的字段。
Available Tools
97 toolsadd_test_stepsA
Insert steps into a STEP_BY_STEP script without losing the existing ones (GET then PUT /testcase/{testCaseKey}): reads the current steps, keeps their ids, splices the new ones in and writes the whole list back — needed because PUT deletes every step missing from the list it receives. The stored steps are ordered by their authoritative index before merging, because GET /testcase serves them in an arbitrary array order once a case has been edited; only the insertion changes, existing step ids and their sequence are preserved. position selects the insertion point: "append" (the default), "prepend", or a 0-based index into that ordered sequence, clamped to the step count. Allowed when the current script is STEP_BY_STEP, and when the case has no script CONTENT yet — a case created without a testScript is reported by the API as an empty PLAIN_TEXT script (a stub with no text), and that counts as script-less: a STEP_BY_STEP script is then created. A PLAIN_TEXT or BDD script that really has text is refused; replace it with set_test_script. A step whose "Call to Test" points at its own case is refused too: the API answers 2xx to such a write and stores NOTHING. After the write the tool reads the case back (a second GET) and returns { key, totalSteps } where totalSteps is the count STORED on the case, not the count sent. When the two differ — the stand accepts a write and silently throws it away — the answer also carries stepsSent and a warning saying so; totalSteps is null with a warning when the read-back itself failed.
Inputs: steps (required), testCaseKey (required), position.
clone_test_caseA
Copy a test case inside its own project (GET /testcase/{testCaseKey}, then POST /testcase). Copies name, objective, precondition, folder, status, priority, component, owner, estimatedTime, labels, custom fields, parameters and — unless includeScript is false — the script; step ids are dropped so the copy owns its steps. Issue links, attachments and execution history are NOT copied. name defaults to " (copy)" and folder to the source folder. The folder MUST already exist — the API never creates folders implicitly (use create_folder first). A test case name is limited to 255 CHARACTERS, not bytes (the API rejects a longer one with an opaque HTTP 500): an explicit longer name is refused locally before any request, and the default name is shortened to fit — the copied source name is cut on a whole-character boundary (an astral character is dropped rather than split), the " (copy)" marker is kept, and note reports both lengths. An explicitly empty name ("") is sent as-is and rejected with 400 "The field name is required." — omit the parameter to get the default. Names are not deduplicated: cloning twice gives two cases with the same name, and cloning a copy gives "… (copy) (copy)" — unless the source name is already at the limit, where the shortening cuts exactly the previous " (copy)" off and the copy ends up named identically to its source (note says so; pass an explicit name to tell them apart). With includeScript=false the copy has no steps, but the API still reports an empty PLAIN_TEXT testScript — that is what every script-less case looks like here. Returns { key, url, sourceKey, note? }.
Inputs: testCaseKey (required), name, folder, includeScript.
create_environmentA
Create a Zephyr Scale environment in a project (POST /environments). The name must be unique within the project — a duplicate is rejected with 400 — and is the string other tools use to reference the environment, so create it with the exact casing you intend to pass to test results. Returns the created environment object as the API sends it.
Inputs: name (required), projectKey, description.
create_folderA
Create a folder for test cases, test plans or test runs / test cycles (POST /folder). name is the FULL path from the root, not a single segment, and every segment must be non-empty and not blank — "/" alone, "/A//B", a trailing "/" and a whitespace-only segment ("/A/ ") are rejected before any HTTP call because the API would create a permanently nameless folder from them. Spaces around a real name are legal and are NOT trimmed. The two rules surface differently: a missing leading "/" is caught by the input schema (an MCP input-validation error), while empty or blank segments are caught by the tool itself (a plain "Invalid folder path ..." message). The other tools never create folders implicitly: create_test_case, create_test_run and create_test_plan fail with 400 on an unknown folder. Not idempotent: an existing path fails with 400 "The folder already exists" and no retry is attempted. With recursive=true (the default) any OTHER 400 on the full path triggers the fallback — every parent prefix is created from the root and the full path is retried once; 403, 409 and 5xx propagate unchanged, so a permission problem is never mistaken for a missing parent. On builds where POST /folder already creates missing ancestors itself that fallback never fires — the reference build is one of them: a two-level-deep new path succeeds even with recursive=false, so recursive is effectively a no-op there. Each folder type has its own tree, so the same path must be created once per type. The public Server/DC API v1 cannot LIST folders, so keep the numeric id returned by create_folder — rename_folder and delete_folder need it (otherwise it can only be found in the Jira UI, or with get_folder_tree when the internal API is enabled). Returns { id, name, type } — id is the id of the LAST segment only, so ancestors created along the way have ids this call never reports (find them with get_folder_tree).
Inputs: name (required), type (required), recursive, projectKey.
create_test_caseA
Create a test case (POST /testcase). The folder MUST already exist — the API never creates folders implicitly (use create_folder first). status, priority, component and custom field names must match the ones configured on the instance and are case-sensitive: an unknown or wrong-case value is rejected with 400 and nothing is created (unlike EXECUTION statuses, which the API silently ignores). owner: Jira user key (e.g. 'JIRAUSER10000'), NOT a username or e-mail — resolve it with find_jira_user. estimatedTime is in milliseconds. name is limited to 255 characters — a longer one is refused locally, because the API answers it with an opaque bodyless HTTP 500. testScript is STEP_BY_STEP with steps, or PLAIN_TEXT/BDD with text; a step carrying testCaseKey is a "Call to Test" that inlines another case. BDD text is stored verbatim and must contain Gherkin step lines only — a "Feature:"/"Scenario:" header is rejected with 400 "Invalid BDD Script". Omitting testScript does NOT leave the case script-less: the server attaches an empty PLAIN_TEXT script, which add_test_steps treats as "no script yet". Returns { key, url }.
Inputs: name (required), owner, folder, labels, +11 more.
create_test_cases_bulkA
Create several test cases in one request (POST /testcase/bulk). Each item takes the same fields as create_test_case; an item without its own projectKey uses the shared projectKey, then ZEPHYR_DEFAULT_PROJECT_KEY. The folder MUST already exist — the API never creates folders implicitly (use create_folder first). Some Server builds ship a broken bulk endpoint (any 5xx, or a JSON 404 — as opposed to the plugin-not-installed HTML 404) while single creation works: the tool then falls back to POST /testcase per item so partial progress survives — on such a build the fallback runs on every call and the bulk shape is never returned. A 4xx from the bulk endpoint is a payload error and is NOT retried. Returns [{ key, url }] on the bulk path, or { note, created: [{ key, url }], failed?: [{ index, name, error }] } when the fallback ran — also when SOME items failed, so always read failed[]. created[] is in input order but carries no index, and failed[] is omitted entirely when every item succeeded; index is the position in the testCases array. When EVERY item fails nothing was created and the call FAILS, with one line per item naming its index, its name and its error, so the payload can be fixed in one pass. A name longer than 255 characters is rejected locally, naming the item.
Inputs: testCases (required), projectKey.
create_test_planA
Create a test plan (POST /testplan). folder must be a TEST_PLAN folder (create_folder with type TEST_PLAN) — The folder MUST already exist — the API never creates folders implicitly (use create_folder first). status is a case-sensitive internal name. owner: Jira user key (e.g. 'JIRAUSER10000'), NOT a username or e-mail — resolve it with find_jira_user. Returns { key } (e.g. "PROJ-P123") — no UI url, because the test plan page has no stable address across Zephyr Scale versions.
Inputs: name (required), owner, folder, labels, +5 more.
create_test_resultA
Record a NEW execution of a run item (POST /testrun/{runKey}/testcase/{caseKey}/testresult). Appends to the execution history of that item — to amend the newest execution instead, use update_last_test_result. Only the fields you pass are sent, and the execution keeps the project default for everything you omit. The test case should already be an item of the run; if it is not, the behavior is VERSION-SPECIFIC — some Server builds silently ADD it to the run as a new item (verified live: testCaseCount grows; the new item's POSITION in items[] is not the head and not the tail — it landed second of three and second of four in two separate runs, so do not rely on where it appears), others reject the call with 400/404. Default statuses: 'Not Executed', 'In Progress', 'Pass', 'Fail', 'Blocked' — case-sensitive internal names; instances may define custom ones. scriptResults carry per-step outcomes of a STEP_BY_STEP script as { index (0-based), status, comment? }. An overall status sent TOGETHER with scriptResults is stored as sent (verified live: 'Blocked' with three 'Pass' steps stored 'Blocked') and is NEVER derived from the step statuses — scriptResults without a status leave the execution at the project default ('Not Executed'), so pass status in the SAME call. Some older builds may instead ignore the overall status: read the result back with get_test_run_results rather than sending a second update_last_test_result, which replaces the whole execution. A scriptResults entry whose index is past the last step of the case is discarded silently (HTTP 200, no error). When the same test case is an item of the run several times (e.g. once per environment or assignee), disambiguate with matchEnvironment / matchUserKey; with no selector the API picks one of them itself — measured live it took the FIRST (lowest-id) twin and left the other untouched, so pass a selector whenever the case appears more than once. Selectors only SELECT an existing item — they never set a value, so pass environment as well if the result should carry it. matchUserKey matches executedBy/userKey, not assignedTo. If nothing matches, this build answers 400 "No test execution found …" or an empty-bodied HTTP 500 — the 500 was first seen with matchEnvironment, but other inputs produce it too, so its cause is undetermined; that empty-bodied 500 has been observed to write the execution and add a duplicate item anyway, so the write may or may not have happened — re-read with get_test_run_results instead of retrying. Returns { id } of the created execution.
Inputs: testRunKey (required), testCaseKey (required), status, comment, +13 more.
create_test_results_bulkA
Record NEW executions for several items of ONE test run in a single call (POST /testrun/{runKey}/testresults). The body is the results array itself; in each entry only the fields you pass are sent, and the returned ids are positionally aligned with it. The test case should already be an item of the run; if it is not, the behavior is VERSION-SPECIFIC — some Server builds silently ADD it to the run as a new item (verified live: testCaseCount grows; the new item's POSITION in items[] is not the head and not the tail — it landed second of three and second of four in two separate runs, so do not rely on where it appears), others reject the call with 400/404. Default statuses: 'Not Executed', 'In Progress', 'Pass', 'Fail', 'Blocked' — case-sensitive internal names; instances may define custom ones. scriptResults carry per-step outcomes of a STEP_BY_STEP script as { index (0-based), status, comment? }. An overall status sent TOGETHER with scriptResults is stored as sent (verified live: 'Blocked' with three 'Pass' steps stored 'Blocked') and is NEVER derived from the step statuses — scriptResults without a status leave the execution at the project default ('Not Executed'), so pass status in the SAME call. Some older builds may instead ignore the overall status: read the result back with get_test_run_results rather than sending a second update_last_test_result, which replaces the whole execution. A scriptResults entry whose index is past the last step of the case is discarded silently (HTTP 200, no error). matchEnvironment / matchUserKey apply to the WHOLE batch and only SELECT which existing run item to append to — they never set the created result's environment. NOT ATOMIC, and it does NOT abort at the failing entry: when one entry is rejected (unknown testCaseKey, bad status/iteration/version value, unknown custom field) the call answers an error and returns no ids, yet that entry alone is SKIPPED while EVERY other valid entry is COMMITTED — the entries AFTER the failing one just as much as those before it (verified live twice, with ids: [valid, valid, unknown key, valid] committed entries 1, 2 and 4; [unknown key, valid] committed entry 2). So after an error that names ONE entry the batch may already be fully written except for that entry: re-read the run with get_test_run_results BEFORE resending anything and resend only the entries that are genuinely missing — resending the batch or its tail creates DUPLICATE executions. An error that rejects the payload as a whole (a malformed body, an unknown run key, a batch-wide matchEnvironment/matchUserKey the API cannot resolve) is different: it is refused before any entry is processed, so nothing was committed and nothing needs re-reading. Two entries for the same test case create two independent executions (no upsert). Returns the array of created executions ([{ id }, …]).
Inputs: results (required), testRunKey (required), matchUserKey, matchEnvironment.
create_test_runA
Create a test run / test cycle (POST /testrun). Pass the COMPLETE list of test cases in items now — API v1 limitation: a test run is IMMUTABLE — there is no PUT /testrun, so it cannot be renamed, moved or have cases added/removed through the public API; its items are fixed at creation and the run status is derived from item statuses. Escape hatches: recreate_test_run_with_items (public, new key) or the internal-API tools update_test_run / add_test_cases_to_run / remove_test_cases_from_run (same key, require ZEPHYR_ALLOW_INTERNAL_API=true). Each item may also carry its execution result (status, executedBy, executionTime, actual dates, per-step scriptResults, …), which imports a run together with its results in one call; afterwards use the test result tools. A run folder is of type TEST_RUN. The folder MUST already exist — the API never creates folders implicitly (use create_folder first). Default statuses: 'Not Executed', 'In Progress', 'Pass', 'Fail', 'Blocked' — case-sensitive internal names; instances may define custom ones. The run's own status is derived by the server from its item statuses and uses a different vocabulary from the execution statuses above ('Not Executed' / 'In Progress' / 'Done'). A run CANNOT be linked to Jira issues: issueLinks is rejected locally because the API has no such field on a run — link the issues on the test cases instead. Returns { key } of the new run.
Inputs: name (required), items, owner, folder, +8 more.
delete_attachmentADestructive
Permanently delete one attachment by its numeric id (DELETE /attachments/{id}). Irreversible, and there is no bulk form — one call per attachment. Ids come from list_attachments or from an upload_attachment response; the entity the attachment belongs to is not needed (ids are global, not per-entity). The DELETE itself answers 2xx even for an id that never existed or was already deleted, so the id is verified FIRST with GET /rest/tests/1.0/attachment/{id} (the one endpoint that 404s for a missing attachment): an unknown id fails without deleting anything, at the cost of downloading the attachment's FULL content first — deleting a large attachment transfers the whole file before removing it. Returns { deleted: true, id, existenceVerified: true }, or existenceVerified: false plus a note when that pre-check itself could not answer (the delete is still attempted, so success then does not prove the id existed).
Inputs: attachmentId (required).
delete_test_caseADestructive
Permanently delete a test case (DELETE /testcase/{testCaseKey}). Irreversible: the case, its script and its execution history cannot be restored through the API. Inbound references are NOT checked: a case that other cases invoke as a "Call to Test" step is deleted anyway and those steps keep pointing at a key that no longer resolves. Returns { deleted: true, key }.
Inputs: testCaseKey (required).
delete_test_planADestructive
Permanently delete a test plan (DELETE /testplan/{testPlanKey}). Irreversible — there is no trash and no undo. NOT idempotent and it never confirms a deletion it did not perform: an unknown, mistyped or already-deleted key answers 404 and this tool fails instead of returning { deleted: true } (verified live). The key is not reused afterwards — the next create_test_plan gets a fresh number. Does NOT cascade to the test runs linked to the plan (verified live): the runs survive with their names, testCaseCount and status intact, only the plan↔run trace links die. Delete the runs separately with delete_test_run if that is what you meant. Returns { deleted: true, key }.
Inputs: testPlanKey (required).
delete_test_runADestructive
Permanently delete a test run / test cycle together with ALL its execution results, its attachments and its test-plan links (DELETE /testrun/{key}). Cannot be undone. API v1 limitation: a test run is IMMUTABLE — there is no PUT /testrun, so it cannot be renamed, moved or have cases added/removed through the public API; its items are fixed at creation and the run status is derived from item statuses. Escape hatches: recreate_test_run_with_items (public, new key) or the internal-API tools update_test_run / add_test_cases_to_run / remove_test_cases_from_run (same key, require ZEPHYR_ALLOW_INTERNAL_API=true). So delete + create_test_run with the full desired items is the public way to change a run's name, folder or composition (the new run gets a NEW key). The DELETE itself answers 2xx for a key that never existed, was already deleted or belongs to another entity type (a TEST CASE key was reported deleted while the case stayed intact), so the key is verified FIRST with GET /testrun/{key}: an unknown key fails without deleting anything. Returns { deleted: true, key, existenceVerified: true }, or existenceVerified: false plus a note when that pre-check itself could not answer (the delete is still attempted, so success then does not prove the run existed).
Inputs: testRunKey (required).
download_attachmentARead-only
Download the content of an attachment to a local file (GET /rest/tests/1.0/attachment/{id}). Address it by attachmentId or by the exact url list_attachments returns — pass exactly one of the two. Attachment content lives outside API v1: /rest/tests/1.0/attachment/{id} is the url the official list endpoint itself hands out, so this tool follows it without requiring ZEPHYR_ALLOW_INTERNAL_API. A supplied url must be on the configured Jira host — credentials are never sent to another host. A query string on the url is sent as request parameters rather than kept in the path, so it is never echoed in an error message (error messages carry the method and the path only, because a query string can carry a token). outputPath is written on the machine running this MCP server and its parent directory must already exist; a failed download writes nothing. Jira answers a url that is not attachment content (a login redirect, an unknown path) with HTTP 200 and an HTML PAGE, so a response whose body starts with or is refused and nothing is written — { savedTo, bytes } therefore means the bytes really came from the attachment endpoint. The refusal names the page it caught (its , or the page's first readable text when it has none) so a login redirect, an error page and a wrong host can be told apart. Set allowHtml: true for an attachment that genuinely is an HTML file. Markup that is not a page (XML, SVG) is never affected. Returns { savedTo, bytes }.
Inputs: outputPath (required), url, allowHtml, attachmentId.
download_feature_filesARead-only
Export BDD test cases as Gherkin .feature files packed in a ZIP archive (GET /automation/testcases). tql is REQUIRED — the API rejects the call without it — and this endpoint uses the testCase.-prefixed TQL dialect, which supports ONLY the fields testCase.key, testCase.projectKey and testCase.name (= and IN) joined by AND: testCase.folder, testCase.status, testCase.priority and testCase.labels are rejected with 400 "Error executing TQL", so a whole folder cannot be exported — select the cases with testCase.key IN (...) instead. Values must be quoted, single or double quotes both work, and spaces around operators are optional here, unlike search_test_cases; lowercase "and", lowercase "testcase." and OR are not accepted, and an OR query answers 200 with an empty body rather than a syntax error. Only cases whose script type is BDD are exported: STEP_BY_STEP and PLAIN_TEXT cases, and keys in an IN list that do not exist, are silently skipped (332 cases yielded 251 .feature files on the reference instance) and the return value does not say which keys were dropped. A query that matches no BDD case — a nonexistent projectKey included — returns HTTP 200 with an EMPTY body, not an empty ZIP, and this tool then reports that the query matched nothing. The archive is flat: one .feature per case, no directories. The server writes "Feature: ", " @TestCaseKey=", " Scenario: ", a blank line, then every stored BDD line prefixed with exactly 8 spaces, so an exported file is only byte-identical to the stored script after that prefix is removed, and it is NOT accepted back by set_test_script / create_test_case (400 "Invalid BDD Script") until the Feature:/@TestCaseKey/Scenario: header is stripped. The archive is written to outputPath only after its 'PK' signature is verified, so an HTML login or error page served with HTTP 200 fails loudly instead of leaving a corrupt file. outputPath's parent directory must already exist, '~' is NOT expanded, and an existing file at outputPath is overwritten without warning on success (a failed call leaves it byte-identical). Reads from Zephyr only, so it stays available in ZEPHYR_READONLY mode. Returns { savedTo, bytes }.
Inputs: tql (required), outputPath (required).
find_jira_userARead-only
Search Jira users (GET /rest/api/2/user/search). Use it to resolve the Jira USER KEY (e.g. "JIRAUSER10000") that the owner / executedBy / assignedTo fields of the other tools require — those fields reject usernames and e-mail addresses. Needs the Jira "Browse users" permission, otherwise Jira answers 403. Returns an array of { key, name, displayName, emailAddress }, empty when nothing matches; emailAddress is absent when Jira hides it.
Inputs: query (required), maxResults.
get_issue_test_coverageARead-only
Traceability report for a Jira issue: every linked test case with its latest execution (GET /issuelink/{issueKey}/testcases, then GET /testcase/{key} and GET /testcase/{key}/testresult/latest per case). Costs up to 2 requests per case, so maxCases (integer 1..200, default 50) caps the volume. totalLinked counts LINKS — the API returns one entry per link, so a case linked to the issue twice is counted twice — while cases[] holds one row per DISTINCT case, expanded once. The order the API supplies is not stable between calls, so which cases survive the maxCases cut may vary; the cap is applied AFTER duplicate links are collapsed, so it counts DISTINCT cases. lastResult is { status, environment?, actualEndDate?, executedBy?, comment? } with the absent keys OMITTED, and it carries no execution id/key (use get_latest_result_for_test_case when you need the id). It is the most recently CREATED execution, not the one with the greatest actualEndDate, so a back-dated execution still wins and the date shown may be older than that of a suppressed one. lastResult null means no latest execution could be resolved — never executed, or its test run was deleted — not "untested" by itself; with includeLastResults=false (it defaults to true) the key is absent entirely. Fault-tolerant: a case that cannot be read still appears with its key. An issue with no linked cases returns totalLinked 0 and an empty cases[]; an issue key that does not exist raises 404 (Jira resolves issue keys case-insensitively, and issueKey is echoed back exactly as passed). note is present only when something was truncated or collapsed. Returns { issueKey, totalLinked, returned, note?, cases: [{ key, name, status, lastResult? }] }.
Inputs: issueKey (required), maxCases, includeLastResults.
get_latest_result_for_test_caseARead-only
Read ONE execution of a test case across ALL test runs (GET /testcase/{key}/testresult/latest). WHICH one is the API's choice and it is not the plain "newest": measured live with three executions of one case, it returned the most recently CREATED one (highest id) even though another carried a later execution date, and back-dating the winner did not dislodge it — so neither "latest by date" nor "latest by date you set" is a safe reading. Treat the answer as "an execution the API considers current" and, whenever the specific execution matters, read the run with get_test_run_results instead. Answers 404 when the case has never been executed. Returns the execution object as the API stores it (id, testCaseKey, status, environment, executedBy, scriptResults, …). Read-back quirks seen live: executionDate mirrors actualEndDate, executedBy is duplicated as userKey (both absent when there is no executor), every result created through the API carries automated: true, issueLinks come back as traceLinks, and a case with no script still returns one stepless scriptResults entry.
Inputs: testCaseKey (required).
get_test_caseARead-only
Read one test case (GET /testcase/{testCaseKey}). A STEP_BY_STEP script comes back with a numeric id on every step; those ids are what update_test_case and set_test_script match on, so read them before editing steps by hand (add_test_steps does it for you). Returns the test case object as the API sends it, restricted to fields when given.
Inputs: testCaseKey (required), fields.
get_test_cases_linked_to_issueARead-only
List the test cases linked to a Jira issue (GET /issuelink/{issueKey}/testcases) — traceability from a requirement or bug to its tests. Create such links with link_issues_to_test_cases, or with the issueLinks field of create_test_case. Use get_issue_test_coverage instead to also see the latest execution of each case. Returns the API array of test case objects, one entry per LINK: a case linked to the issue twice appears twice, and the order is not stable between calls — de-duplicate by key before counting. Entries carry the API fields, including lastTestResultStatus — a DENORMALIZED value that is absent while the case has never been executed and is reset to "Not Executed" (not cleared) when the test run holding its executions is deleted, so it can read "Not Executed" for a case that really ran Pass. get_issue_test_coverage resolves the execution live and reports lastResult null in that situation; prefer it when the distinction matters.
Inputs: issueKey (required).
get_test_planARead-only
Read a test plan by key (GET /testplan/{testPlanKey}). The payload embeds the linked test runs and Jira issues when the plan has any; narrow it with fields. Returns the test plan object as the API sends it.
Inputs: testPlanKey (required), fields.
get_test_runARead-only
Read one test run / test cycle including its items (GET /testrun/{key}). API v1 limitation: a test run is IMMUTABLE — there is no PUT /testrun, so it cannot be renamed, moved or have cases added/removed through the public API; its items are fixed at creation and the run status is derived from item statuses. Escape hatches: recreate_test_run_with_items (public, new key) or the internal-API tools update_test_run / add_test_cases_to_run / remove_test_cases_from_run (same key, require ZEPHYR_ALLOW_INTERNAL_API=true). Use get_test_run_results for the executions of the run and get_test_run_summary for status counts. items[].id is the id of that item's LATEST EXECUTION, not a stable item identifier: it changes with every new result, and it is a different id space from remove_test_cases_from_run's removedItemIds. Returns the run object as the API stores it (key, name, status, owner, folder, items, …), or only the requested fields.
Inputs: testRunKey (required), fields.
get_test_run_resultsARead-only
Page through the execution results of a test run / test cycle (GET /testrun/{key}/testresults/page). An item can have several executions; onlyLastExecutions=true keeps only the most recent one per item, so it never returns more values than the run has items. Creating a run already seeds one 'Not Executed' execution per item (that execution IS the item's last one), so with onlyLastExecutions=false — the default — total starts at the item count, not at 0. Older Zephyr Scale builds have no /page endpoint: the deprecated flat GET /testrun/{key}/testresults is then read and paginated client-side, and onlyLastExecutions is resolved from the run object, whose items[] name the id of each item's last execution; the note in the response says which path produced the values (a run that does not exist still surfaces as a 404). Values come in the order the API returns them, which is neither run-item order nor execution order. Returns { startAt, maxResults, total, count, isLast, values, note? } where total is the size of the set being paged — the number of results on the server, or the post-deduplication count when onlyLastExecutions is true — and isLast is startAt + count >= total.
Inputs: testRunKey (required), startAt, maxResults, onlyLastExecutions.
get_test_run_summaryARead-only
Aggregated execution summary of a test run / test cycle: composite read-only call of GET /testrun/{key} plus every page of its results (with the flat-endpoint fallback of get_test_run_results). Counts the LAST execution of each item — the run object names them, so latestResults and executed never exceed itemCount — grouping by status name verbatim in byStatus; nothing is normalized. Default statuses: 'Not Executed', 'In Progress', 'Pass', 'Fail', 'Blocked' — case-sensitive internal names; instances may define custom ones. runStatus is the status of the RUN itself (e.g. 'In Progress', 'Done'), not an execution status. executed counts every counted result whose status is not the literal 'Not Executed'. executionProgressPct = executed/itemCount (executed/latestResults when the run exposes no items), so an item with no counted last execution counts as not executed and note says how many there are. passRatePct is the share of the literal status 'Pass' among executed — 0 when nothing passed, and absent only when executed is 0. Returns { key, name, runStatus, itemCount?, latestResults, executed, executionProgressPct?, byStatus, passRatePct?, note? }.
Inputs: testRunKey (required).
health_checkARead-only
Verify connectivity and credentials (GET /rest/api/2/myself) and, when ZEPHYR_DEFAULT_PROJECT_KEY is configured, whether the Zephyr Scale plugin answers on /rest/atm/1.0 (GET /environments). Any JSON error from the plugin — including 403 for a project without Zephyr — still counts as reachable; only Jira's generic HTML 404 page or a network failure counts as unreachable. The tool itself fails only when Jira does not answer or rejects the credentials. Returns { ok: true, jiraUser, baseUrl, zephyrPluginReachable } — zephyrPluginReachable is omitted when no default project key is set.
Inputs: no named parameters.
jira_add_commentB
Add a comment (Server takes wiki markup, not Markdown)
Inputs: key (required), body (required). Returns: comment
jira_add_issues_to_sprintC
Move issues into a sprint
Inputs: issues (required), sprintId (required).
jira_add_watcherA
Add a user as a watcher of an issue
Inputs: key (required), username (required).
jira_add_worklogC
Log work against an issue
Inputs: key (required), started (required), timeSpentSeconds (required), comment. Returns: worklog entry
jira_assign_issueC
Assign an issue
Inputs: key (required), assignee (required).
jira_create_issueA
Create an issue. Call jira_describe_create first for the field template; keys may be field ids or business aliases
Inputs: fields (required). Returns: result of creating an issue
jira_create_remote_linkC
Attach a remote link (e.g. a Confluence page) to an issue
Inputs: key (required), url (required), title (required), relationship.
jira_delete_attachmentCDestructive
Delete an attachment
Inputs: id (required).
jira_delete_commentCDestructive
Delete a comment
Inputs: key (required), commentId (required).
jira_delete_issueCDestructive
Delete an issue
Inputs: key (required), deleteSubtasks.
jira_delete_linkADestructive
Delete an issue link by its id (find ids in the issue's issuelinks field)
Inputs: linkId (required).
jira_delete_worklogCDestructive
Delete a worklog
Inputs: key (required), worklogId (required).
jira_describe_createARead-only
Call before creating an issue. Returns the fields writable for this project/type, which are required, their value shapes and allowed values
Inputs: projectKey (required), issueTypeName (required).
jira_describe_editARead-only
Call before updating an issue. Returns the fields editable on this issue right now (already filtered by workflow/screen)
Inputs: key (required).
jira_get_attachment_metaBRead-only
Get attachment metadata (filename/size/author/download url)
Inputs: id (required). Returns: attachment
jira_get_board_issuesCRead-only
List the issues on a board
Inputs: boardId (required), jql, maxResults. Returns: Agile issue list
jira_get_componentsCRead-only
List the components of a project
Inputs: key (required).
jira_get_current_userBRead-only
Get the authenticated user
Inputs: no named parameters. Returns: user
jira_get_fieldsARead-only
List every field, plugin-provided ones included. Use it to obtain field ids
Inputs: no named parameters.
jira_get_issueARead-only
Get an issue. Returns all fields by default, custom fields included. Use expand to pull extra sections in the same call (e.g. changelog, renderedFields, transitions)
Inputs: key (required), expand, fields. Returns: Jira issue
jira_get_issue_typesBRead-only
List issue types
Inputs: no named parameters.
jira_get_link_typesARead-only
List issue link types. Use the returned name as the link type when linking issues
Inputs: no named parameters. Returns: issue link types
jira_get_prioritiesCRead-only
List priorities
Inputs: no named parameters.
jira_get_projectCRead-only
Get project details
Inputs: key (required). Returns: project
jira_get_remote_linksARead-only
List the remote links (e.g. Confluence pages) attached to an issue
Inputs: key (required).
jira_get_sprintCRead-only
Get a sprint by id
Inputs: sprintId (required). Returns: Agile sprint
jira_get_sprint_issuesCRead-only
List the issues in a sprint
Inputs: sprintId (required), jql, maxResults. Returns: Agile issue list
jira_get_statusesCRead-only
List the statuses of a project
Inputs: key (required).
jira_get_transitionsARead-only
List the transitions currently available for this issue
Inputs: key (required). Returns: available transitions for an issue
jira_get_userCRead-only
Get a user by username
Inputs: username (required). Returns: user
jira_get_versionsBRead-only
List the versions of a project
Inputs: key (required).
jira_get_watchersARead-only
List the watchers of an issue, and whether the authenticated user is watching
Inputs: key (required). Returns: watchers of an issue
jira_jsm_queuesCRead-only
List Jira Service Management queues
Inputs: serviceDeskId (required). Returns: Agile paged result
jira_link_issuesA
Link two issues. type is a link type name from jira_get_link_types. The response carries no id - read the issue's issuelinks field to get it
Inputs: type (required), inwardIssue (required), outwardIssue (required), comment.
jira_list_attachmentsARead-only
List the attachments of an issue (id and download url included)
Inputs: key (required). Returns: attachments of an issue (fields.attachment)
jira_list_backlogCRead-only
List the backlog of a board
Inputs: boardId (required). Returns: Agile issue list
jira_list_boardsCRead-only
List boards
Inputs: projectKey. Returns: Agile paged result
jira_list_commentsCRead-only
List the comments of an issue
Inputs: key (required). Returns: comment list
jira_list_pluginsARead-only
List installed UPM plugins when the account may read /rest/plugins/1.0. If UPM is unavailable, falls back to inferring plugin keys from custom field schemas and reports why each UPM path failed
Inputs: no named parameters. Returns: UPM plugin list, or a field-derived inference when UPM is unavailable
jira_list_projectsCRead-only
List projects
Inputs: no named parameters.
jira_list_sprintsCRead-only
List the sprints of a board
Inputs: boardId (required), state. Returns: Agile paged result
jira_list_worklogsCRead-only
List the worklogs of an issue
Inputs: key (required). Returns: worklog list
jira_move_issues_to_backlogC
Move issues to the backlog
Inputs: issues (required).
jira_remove_watcherCDestructive
Remove a user from the watchers of an issue
Inputs: key (required), username (required).
jira_requestA
Raw Jira REST call. The escape hatch for plugin modules that have no dedicated tool yet
Inputs: path (required), method (required), body, query.
jira_scriptrunner_runC
Run a ScriptRunner custom endpoint
Inputs: name (required), payload. Returns: any JSON object; only the envelope is known
jira_search_assignableARead-only
Search users assignable to an issue
Inputs: key (required), query.
jira_search_issuesCRead-only
Search issues with JQL
Inputs: jql (required), fields, startAt, maxResults. Returns: JQL search result
jira_search_usersBRead-only
Search users (Server matches on username, not accountId)
Inputs: query (required), maxResults.
jira_server_infoARead-only
Get Jira version information (useful to confirm the Server version and deployment type)
Inputs: no named parameters. Returns: Jira version information
jira_transition_issueC
Apply a workflow transition
Inputs: key (required), transitionId (required), fields.
jira_update_commentD
Update a comment
Inputs: key (required), body (required), commentId (required). Returns: comment
jira_update_issueA
Update an issue. Call jira_describe_edit first; use update for add/remove on multi-value fields
Inputs: key (required), fields, update.
jira_update_worklogC
Update a worklog
Inputs: key (required), worklogId (required), comment, started, +1 more. Returns: worklog entry
jira_upload_attachmentC
Upload a local file as an issue attachment (multipart)
Inputs: key (required), filePath (required).
link_issues_to_test_casesAIdempotent
Link Jira issues to test cases in bulk (POST /testcase/link-issues). One entry links one test case to one issue; repeat a testCaseKey across entries to link it to several issues. At most 2500 UNIQUE test case keys per call — checked locally, before any request. Additive: it only creates links, never removes existing ones. KNOWN ISSUE: on many Server/DC builds this endpoint answers HTTP 500 with an empty body even for a single valid pair (verified live on such a stand); link through update_test_case (or create_test_case) with the issueLinks field instead — that field REPLACES the case's whole link set, so send the complete final list. Returns the API payload, or { linked: } when the API answers with an empty body (the usual case).
Inputs: links (required).
list_attachmentsARead-only
List the attachments of a test case, test run (cycle), test result, or of one step of a case or result (GET /testcase/{key}[/step/{i}]/attachments, /testrun/{key}/attachments, /testresult/{id}[/step/{i}]/attachments). Addressing: 'test_case' needs testCaseKey, 'test_run' needs testRunKey, 'test_result' needs testResultId (numeric); an identifier that does not match the target is rejected. stepIndex is accepted for 'test_case' and 'test_result' only — API v1 has no per-step attachments endpoint for runs. These endpoints take no pagination and no fields projection — the full list always comes back. Step attachments are aggregated ASYMMETRICALLY (verified live): the test-case list EXCLUDES attachments that live on the case steps, while the test-result list INCLUDES them — so enumerating a case's evidence needs one extra call per step, and doing the same on a result double-counts. An out-of-range stepIndex answers 404 (an in-range step with no attachments answers []), and a testResultId that does not exist answers [] rather than 404, unlike a bogus test case or run key. Returns the API's array of attachment records as-is; each record carries the numeric id delete_attachment needs and the url download_attachment accepts.
Inputs: target (required), stepIndex, testRunKey, testCaseKey, +1 more.
list_environmentsARead-only
List the Zephyr Scale environments of a project (GET /environments?projectKey=…). Environments are per-project and are referenced BY NAME (case-sensitive) in test run items and test results, so use this to get the exact spelling. Returns the raw array of environment objects ([{ id, name, description }]); an empty array means the project defines none.
Inputs: projectKey.
move_test_cases_to_folderA
Move test cases into another folder — one partial PUT /testcase/{key} per case that changes only the folder field. Select the cases with EITHER testCaseKeys OR fromFolder (resolved by GET /testcase/search on folder = ""): exactly one of the two, checked before any request. fromFolder matches that folder EXACTLY — cases in its subfolders are not included, and an existing but empty fromFolder moves nothing. The folder MUST already exist — the API never creates folders implicitly (use create_folder first). The TARGET folder is NOT checked before the requests: a path that does not exist still issues one PUT per case, every one of them fails with 400 and the call resolves with movedCount 0 — always read failed[], since the returned folder only echoes what was asked for. Folder paths are case-sensitive and the root "/" is not a valid target (400 "The value / was not found for field folder"), so a case cannot be moved out of all folders here. Duplicate testCaseKeys are de-duplicated: each case is moved once and movedCount counts distinct cases. maxCases caps both selection modes. A failing case does not abort the rest — it is reported in failed. Only the folder field is written (script, step ids, version, labels, status, priority, owner, objective and precondition are preserved) and moving is reversible (move them back the same way). De-duplication is by EXACT string: keys are neither trimmed nor upper-cased, so "PROJ-T1" and "proj-t1" are two candidates and the second one simply fails with 404 on this case-sensitive API. movedCount counts successful writes, so a case already sitting in the target folder counts as moved. maxCases is applied AFTER the duplicates are removed, and note appears only when something needs explaining (cap truncation, ignored duplicates) — a clean full move and an empty fromFolder both return no note. A fromFolder path that does not exist is different from an empty one: the underlying search fails with 400 "Value(s) not found for field folder". Each failed[] entry is { key, error }. Returns { folder, movedCount, moved, failed?, note? }.
Inputs: folder (required), maxCases, fromFolder, projectKey, +1 more.
recreate_test_run_with_itemsADestructive
Recreate a test run (cycle) under a NEW key with a changed item list, name or folder (GET /testrun/{key} + POST /testrun, plus DELETE /testrun/{key} when deleteOriginal=true). API v1 limitation: a test run is IMMUTABLE — there is no PUT /testrun, so it cannot be renamed, moved or have cases added/removed through the public API; its items are fixed at creation and the run status is derived from item statuses. Escape hatches: recreate_test_run_with_items (public, new key) or the internal-API tools update_test_run / add_test_cases_to_run / remove_test_cases_from_run (same key, require ZEPHYR_ALLOW_INTERNAL_API=true). Items of the new run are: the source items in their original order, minus removeTestCaseKeys, plus addItems appended; of the source items only the planning fields (testCaseKey, environment, assignedTo) are carried over when copyResults is false — all read-only item data is dropped. The new run gets a NEW key and nothing that referenced the old one is updated. Header fields not passed explicitly are inherited from the source run (a JSON null there counts as absent) — EXCEPT testPlanKey, which GET /testrun does not report at all, so the new run starts with no plan association unless you pass it (or re-link with link_test_run_to_plan). A run cannot carry Jira issue links at all: issueLinks is rejected locally, and any value the source run reports is dropped rather than forwarded — link the issues on the test cases instead. removeTestCaseKeys filters the SOURCE items only: a key that also appears in addItems is still added. deleteOriginal runs only after POST /testrun succeeded, so a failed create leaves the source run untouched. copyResults=true carries each kept case's LAST execution over as the initial result of its item, while the item's own environment/assignedTo still win — but GET /testrun reports each item MERGED with its latest execution, so an item whose configured environment/assignedTo were not repeated in that execution has already lost them before this tool reads the run; set them explicitly through addItems when specific values matter. Copied per-step scriptResults are sanitized: this API stores the execution of a case without a STEP_BY_STEP script as an index-less stub, and POST /testrun requires an index on every entry, so entries without a usable index are numbered by position or dropped. removeTestCaseKeys is a SILENT filter (keys that are not items of the run, including nonexistent ones, are ignored), addItems does NOT deduplicate (adding a case that is already an item creates a second item for it, after which test results for that case need matchEnvironment/matchUserKey), and removing every item is allowed and produces a valid run with zero items. The source run survives unless deleteOriginal=true, and is never deleted when creating the new run failed. Returns { key, originalKey, itemCount, copiedResults, deletedOriginal } plus copyResultsNote when result copying hit its page cap. copiedResults counts the KEPT SOURCE items that had a last execution — including the 'Not Executed' execution the server writes for every item at creation, so it is not a count of real executions; addItems entries are never counted, even when they carry a status.
Inputs: testRunKey (required), name, owner, folder, +11 more.
rename_folderAIdempotent
Rename a folder and/or set its custom fields (PUT /folder/{folderId}). name replaces the name of that ONE folder segment — it is not a path, so it cannot move the folder to another parent, and an empty or whitespace-only name, or "/" or "" in it, is rejected before any HTTP call. The rename changes the full path of this folder and of every folder below it, so paths held elsewhere (the folder argument of create_test_case / create_test_run, TQL folder filters) must be updated afterwards. The API does NOT enforce sibling-name uniqueness here (verified live): renaming a folder to the name of an existing sibling succeeds and leaves two siblings with one name — an ambiguous path — even though create_folder rejects that same path with 400 "already exists". The public Server/DC API v1 cannot LIST folders, so keep the numeric id returned by create_folder — rename_folder and delete_folder need it (otherwise it can only be found in the Jira UI, or with get_folder_tree when the internal API is enabled). Returns { id, name }, where name is the new SINGLE segment — unlike create_folder, which echoes the full path.
Inputs: name (required), folderId (required), customFields.
search_test_casesARead-only
Search test cases with a TQL query (GET /testcase/search). A query longer than 1500 characters is sent as POST /testcase/search instead, which supports ONLY the fields projectKey, key and name and at most 2500 values per IN list. That POST endpoint is missing or broken on some Zephyr Scale Server builds, so prefer staying under 1500 characters (split a long IN list across calls); when a POST search fails the error says which transport was used and why.
Unknown VALUES are validated inconsistently: an unknown status, priority, component or projectKey is rejected with 400, while an unknown label in an IN list and an unknown key inside key IN (…) are silently skipped and just shrink the result set — a typo there is indistinguishable from no match. isLast is a heuristic, so an exactly full page always reports isLast false even when it is the last one: stop when values is empty.
TQL quick reference:
Test case fields: projectKey, key, name, status, priority, component, folder, estimatedTime, labels, owner, issueKeys + custom fields (field name in double quotes).
Test run (cycle) fields: ONLY projectKey and folder.
Operators: =, >, >=, <, <=, IN; the only logical connector is AND (no OR).
Syntax is strict: spaces around operators are mandatory, string values in double quotes. Folder paths start with "/" ("/" is the root). For single/multi-choice custom fields '=' does not work — use IN.
Examples: projectKey = "PROJ" AND status = "Draft" AND priority = "High" projectKey = "PROJ" AND folder = "/Regression/Payments" projectKey = "PROJ" AND labels IN ("smoke", "ui") projectKey = "PROJ" AND "My Field" IN ("Value") key IN ("PROJ-T50", "PROJ-T90") projectKey = "PROJ" AND issueKeys IN ("PROJ-5")
Returns { startAt, maxResults, count, isLast, values }; isLast is the heuristic count < maxResults. Paginate with startAt (default 0) and maxResults (default 50; the API server-side default is 200).
Inputs: query (required), fields, startAt, maxResults.
search_test_plansARead-only
Search test plans with a TQL query (GET /testplan/search). For test plans the searchable fields include projectKey, folder, name, status, key, owner and labels (verified live) — the exact set varies by Zephyr Scale version, and an unsupported field fails with 400 "Unrecognized field: ".
folder matches EXACTLY: plans in a subfolder of the given path are NOT returned. A folder path that does not exist is not an error here — it comes back as an empty page (count 0), unlike search_test_cases and search_test_runs, which answer 400 for the same path.
TQL quick reference:
Test case fields: projectKey, key, name, status, priority, component, folder, estimatedTime, labels, owner, issueKeys + custom fields (field name in double quotes).
Test run (cycle) fields: ONLY projectKey and folder.
Operators: =, >, >=, <, <=, IN; the only logical connector is AND (no OR).
Syntax is strict: spaces around operators are mandatory, string values in double quotes. Folder paths start with "/" ("/" is the root). For single/multi-choice custom fields '=' does not work — use IN.
Examples: projectKey = "PROJ" AND status = "Draft" AND priority = "High" projectKey = "PROJ" AND folder = "/Regression/Payments" projectKey = "PROJ" AND labels IN ("smoke", "ui") projectKey = "PROJ" AND "My Field" IN ("Value") key IN ("PROJ-T50", "PROJ-T90") projectKey = "PROJ" AND issueKeys IN ("PROJ-5")
Returns { startAt, maxResults, count, isLast, values }; isLast is the heuristic count < maxResults. Paginate with startAt (default 0) and maxResults (default 50; the API server-side default is 200).
Inputs: query (required), fields, startAt, maxResults.
search_test_runsARead-only
Search test runs / test cycles with TQL (GET /testrun/search). For runs TQL accepts ONLY the fields projectKey and folder — name, status or dates are NOT searchable, and there is no full-text search; read a candidate run with get_test_run instead. A folder clause matches that folder AND its subfolders: folder = "/A" also returns the runs in /A/B. TQL quick reference:
Test case fields: projectKey, key, name, status, priority, component, folder, estimatedTime, labels, owner, issueKeys + custom fields (field name in double quotes).
Test run (cycle) fields: ONLY projectKey and folder.
Operators: =, >, >=, <, <=, IN; the only logical connector is AND (no OR).
Syntax is strict: spaces around operators are mandatory, string values in double quotes. Folder paths start with "/" ("/" is the root). For single/multi-choice custom fields '=' does not work — use IN.
Examples: projectKey = "PROJ" AND status = "Draft" AND priority = "High" projectKey = "PROJ" AND folder = "/Regression/Payments" projectKey = "PROJ" AND labels IN ("smoke", "ui") projectKey = "PROJ" AND "My Field" IN ("Value") key IN ("PROJ-T50", "PROJ-T90") projectKey = "PROJ" AND issueKeys IN ("PROJ-5") Returns { startAt, maxResults, count, isLast, values }; isLast is the heuristic count < maxResults. Paginate with startAt (default 0) and maxResults (default 50; the API server-side default is 200).
Inputs: query (required), fields, startAt, maxResults.
set_test_scriptADestructiveIdempotent
Replace a test case's whole script or change its format (PUT /testcase/{testCaseKey} with a full testScript). DESTRUCTIVE: switching STEP_BY_STEP to PLAIN_TEXT or BDD irreversibly deletes all steps, and a STEP_BY_STEP replacement deletes every stored step whose id is absent from steps. text is required for PLAIN_TEXT and BDD, steps for STEP_BY_STEP — the pairing is validated locally, before any request — but steps: [] passes that check and DELETES every stored step, leaving an empty STEP_BY_STEP script. BDD text is stored verbatim and must contain Gherkin step lines only, no "Feature:"/"Scenario:" header (400 "Invalid BDD Script"). A step whose "Call to Test" points at its own case is refused locally: the API answers 2xx to such a write and stores NOTHING. After the write the tool reads the case back (a second GET) and compares the STORED script with the one sent — its type, the step count for STEP_BY_STEP, and that a non-empty text survived for PLAIN_TEXT/BDD (the text itself is not compared byte-for-byte). Returns { key, url }; when the stand accepted the write and kept the old script, the answer also carries storedType, storedSteps and a warning saying what is really stored, and a warning alone when the read-back itself failed.
Inputs: type (required), testCaseKey (required), text, steps.
update_last_test_resultA
Amend the LAST (most recent) execution of a run item (PUT /testrun/{runKey}/testcase/{caseKey}/testresult). The endpoint REPLACES the execution instead of patching it: fields missing from the body are reset (verified live — an omitted status falls back to the project default 'Not Executed', executedBy becomes null, actualEndDate/executionDate jump to the server time; only comment, environment, executionTime, actualStartDate and scriptResults are kept by the API itself). To stop a comment edit from wiping the verdict, this tool therefore first READS the run item's current execution (one extra GET, two requests on builds without /testresults/page) and re-sends what you did not pass: status, executedBy, assignedTo, environment, comment, executionTime, actualStartDate, actualEndDate, iteration, version — exactly as the API returned them, never invented. So omitting a field means "keep it", not "clear it"; a value the API does not return cannot be preserved; and if the pre-read fails or the item has no execution yet, only your fields are sent. Older executions are unreachable here — record a new one with create_test_result, or edit any execution by id with update_test_result_by_id (internal API, when enabled). The test case should already be an item of the run; if it is not, the behavior is VERSION-SPECIFIC — some Server builds silently ADD it to the run as a new item (verified live: testCaseCount grows; the new item's POSITION in items[] is not the head and not the tail — it landed second of three and second of four in two separate runs, so do not rely on where it appears), others reject the call with 400/404. Default statuses: 'Not Executed', 'In Progress', 'Pass', 'Fail', 'Blocked' — case-sensitive internal names; instances may define custom ones. scriptResults carry per-step outcomes of a STEP_BY_STEP script as { index (0-based), status, comment? }. An overall status sent TOGETHER with scriptResults is stored as sent (verified live: 'Blocked' with three 'Pass' steps stored 'Blocked') and is NEVER derived from the step statuses — scriptResults without a status leave the execution at the project default ('Not Executed'), so pass status in the SAME call. Some older builds may instead ignore the overall status: read the result back with get_test_run_results rather than sending a second update_last_test_result, which replaces the whole execution. A scriptResults entry whose index is past the last step of the case is discarded silently (HTTP 200, no error). When the same test case is an item of the run several times (e.g. once per environment or assignee), disambiguate with matchEnvironment / matchUserKey; with no selector the API picks one of them itself — measured live it took the FIRST (lowest-id) twin and left the other untouched, so pass a selector whenever the case appears more than once. Selectors only SELECT an existing item — they never set a value, so pass environment as well if the result should carry it. matchUserKey matches executedBy/userKey, not assignedTo. If nothing matches, this build answers 400 "No test execution found …" or an empty-bodied HTTP 500 — the 500 was first seen with matchEnvironment, but other inputs produce it too, so its cause is undetermined; that empty-bodied 500 has been observed to write the execution and add a duplicate item anyway, so the write may or may not have happened — re-read with get_test_run_results instead of retrying. Returns the API response ({ id } of the amended execution on the audited build), or { updated: true, testRunKey, testCaseKey } when the API answers with an empty body.
Inputs: testRunKey (required), testCaseKey (required), status, comment, +13 more.
update_test_caseAIdempotent
Update a test case (PUT /testcase/{testCaseKey}). PARTIAL: only the fields passed are changed and omitted fields keep their values, so never send empty placeholders. projectKey cannot be changed. issueLinks REPLACES the whole link set instead of adding to it — sending issueLinks: ["PROJ-1"] to a case already linked to PROJ-2 silently unlinks PROJ-2, so read the current links with get_test_case and send the complete final list (link_issues_to_test_cases is the additive alternative). testScript.steps is synchronized BY ID — a step without an id is created, a step with an id is updated, and every stored step whose id is missing from the list is DELETED; always send the complete final list, carrying over the ids from get_test_case. To only add steps use add_test_steps, which does that read-merge-write safely. A name longer than 255 characters is refused locally: the API stores the first 255 characters and still reports success. A step whose "Call to Test" points at its own case is refused locally too: the API answers 2xx to such a write and stores NOTHING, throwing away the other steps of the same request with it. When (and only when) testScript is passed, the tool reads the case back afterwards (one extra GET) and compares the STORED script with the one sent — its type, the step count for STEP_BY_STEP, and that a non-empty text survived for PLAIN_TEXT/BDD (the text itself is not compared byte-for-byte); an update without testScript costs no extra request. The folder MUST already exist — the API never creates folders implicitly (use create_folder first). Returns { key, url }; when the stand accepted the write and kept the old script, the answer also carries storedType, storedSteps and a warning saying what is really stored, and a warning alone when the read-back itself failed. Only the script is verified: the other fields of a partial update are not read back.
Inputs: testCaseKey (required), name, owner, folder, +11 more.
update_test_planAIdempotent
Update a test plan (PUT /testplan/{testPlanKey}). PARTIAL update: only the fields you pass are written and omitted fields keep their current value, so never send empty placeholders — they overwrite real data. projectKey cannot be changed. folder must be a TEST_PLAN folder (create_folder with type TEST_PLAN) — The folder MUST already exist — the API never creates folders implicitly (use create_folder first). status is a case-sensitive internal name. owner: Jira user key (e.g. 'JIRAUSER10000'), NOT a username or e-mail — resolve it with find_jira_user. Returns { key }.
Inputs: testPlanKey (required), name, owner, folder, +5 more.
upload_attachmentA
Attach a local file to a test case, test run (cycle), test result, or to one step of a case or result (POST multipart/form-data /testcase/{key}[/step/{i}]/attachments, /testrun/{key}/attachments, /testresult/{id}[/step/{i}]/attachments). Addressing: 'test_case' needs testCaseKey, 'test_run' needs testRunKey, 'test_result' needs testResultId (numeric); an identifier that does not match the target is rejected. stepIndex is accepted for 'test_case' and 'test_result' only — API v1 has no per-step attachments endpoint for runs. filePath is read from the disk of the machine running this MCP server, not from the caller. Uploads are not idempotent: calling twice creates two attachments. A bogus testResultId is rejected here with 404 even though list_attachments answers [] for it (verified live). Returns the attachment metadata the API reports — on the reference build always a bare { id }, with neither the file name nor the size echoed back, so verifying an upload costs a list_attachments call — or { uploaded: true, fileName, size } when the API answers with an empty body.
Inputs: target (required), filePath (required), fileName, stepIndex, +3 more.
upload_automation_resultsA
Publish automated execution results from a local ZIP archive (POST multipart/form-data /automation/execution/{projectKey}). The archive must hold JSON files in Zephyr's custom results format: {"version": 1, "executions": [{"source", "result", "testCase": {"key"}}]}. Validation is strict only at the TOP level of an execution: an extra sibling of source/result such as executionTime is rejected with 400 "Invalid Custom Format JSON file", while an extra field inside "testCase" is silently accepted; "version" is not validated at all and "source" is optional (and readable back through no endpoint). Each execution's "result" is a status name — Default statuses: 'Not Executed', 'In Progress', 'Pass', 'Fail', 'Blocked' — case-sensitive internal names; instances may define custom ones. WARNING (verified live): an UNRECOGNIZED result value is NOT rejected — "PASS", "pass", "FAIL", "" and free text are all stored as Blocked with HTTP 200, so a single typo turns a green suite into a Blocked cycle silently; only an absent "result" key errors (400 "Test Result Status is required"). Test case keys are case-sensitive and must exist: one bad key rejects the whole archive and creates no partial cycle. Two executions of the SAME case become two separate run items, and several JSON files in one ZIP are merged into one cycle. A 400 "Invalid ZIP file" also means a structurally valid archive that contains no JSON at all. Always creates a NEW test cycle (test run) — it never appends to an existing one — and returns the API description of that cycle unchanged, or { uploaded: true } for an empty body.
Inputs: filePath (required), projectKey, autoCreateTestCases.
upload_cucumber_resultsA
Publish Cucumber execution results from a local ZIP archive (POST multipart/form-data /automation/execution/cucumber/{projectKey}). The archive must hold the output of Cucumber's built-in json formatter (one or more .json report files). Every scenario must carry a @TestCaseKey=PROJ-T1 tag naming the BDD test case it reports on — that tag is how the server matches a scenario to an existing test case. Always creates a NEW test cycle (test run) — it never appends to an existing one — and returns the API description of that cycle unchanged, or { uploaded: true } for an empty body.
Inputs: filePath (required), projectKey, autoCreateTestCases.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 97 tools
Most tools target a distinct resource+action, but the attachment trio is duplicated across domains (jira_list_attachments/jira_upload_attachment/jira_delete_attachment vs list_attachments/upload_attachment/delete_attachment), and create_test_case vs create_test_cases_bulk, create_test_result vs create_test_results_bulk, and the run-result readers (get_test_run_results/get_test_run_summary/get_latest_result_for_test_case) overlap in scope. The extremely detailed, quirk-filled descriptions help an agent choose, but the near-duplicate names still risk misselection.
snake_case is used throughout, but the surface splits into a jira_-prefixed Jira family and an unprefixed Zephyr family, so the same conceptual operation (list_attachments, delete_attachment) appears under two conventions. Within families the verb_noun pattern is mostly consistent, with oddities like jira_list_sprints vs jira_get_sprint and noun-first names such as health_check and find_jira_user.
97 tools is an extreme mismatch for a single server, spanning two large products (Jira core plus Zephyr Scale). The set is far past the 50+ threshold where findability collapses, and many capabilities (bulk vs single, run-result readers, raw jira_request) push the count higher without adding distinct value.
Coverage is exceptional: full CRUD for test cases, runs, plans, folders, results, environments and attachments; test-case scripting (steps, script replacement, clone, bulk, move); traceability/coverage reporting; automation-result ingestion; and Jira issue/comment/worklog/watcher/link/board/sprint operations. Documented gaps (run mutability requiring recreation or internal API) are explicit escape hatches rather than dead ends.
Maintenance
Related MCP Connectors
One OAuth connector for your team's remote MCP servers, with Tool Packs, guardrails and logs.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Discover, plan and run tools across your connected business systems through one OAuth MCP endpoint
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Related MCP Servers
- AlicenseAqualityCmaintenanceAn MCP server for interacting with self-hosted Jira instances using Personal Access Token (PAT) authentication. It enables users to perform CRUD operations on issues, search with JQL, manage comments, and list projects through the Jira REST API.12567 npm16MIT
- FlicenseNot gradedqualityCmaintenanceMCP server for Jira Data Center / Server (self-hosted Jira, REST API v2) that exposes core work-item project-management operations (platform + Agile) as MCP tools.-
- AlicenseNot gradedqualityDmaintenanceZero-dependency MCP server for self-hosted Jira Server/Data Center that supports Basic Auth and PAT, enabling JQL search, issue creation/update, comments, transitions, and assignment on Jira 8.x including pre-8.14.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to manage self-hosted Atlassian Jira Server/Data Center issues and Bitbucket Server/Data Center repositories, pull requests, branches, commits, and files through MCP tools.44 npm4MIT