Zephyr Scale MCP

UNOFFICIAL — internal API: this tool calls /rest/tests/1.0, the same undocumented API the Jira UI uses. The vendor does NOT support it: endpoints may differ or be absent on another Zephyr Scale version. Registered only because ZEPHYR_ALLOW_INTERNAL_API=true. Permanently delete individual test executions (results) by their numeric ids (POST /testresult/bulk/delete with a bare JSON array of ids) — the public API v1 cannot delete results at all, they normally die only together with their run. CANNOT BE UNDONE. CONSTRAINT: the LAST execution of a run item cannot be deleted — the API rejects it wit…

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_INTERNA…

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 i…

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 spac…

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.

UNOFFICIAL — internal API: this tool calls /rest/tests/1.0, the same undocumented API the Jira UI uses. The vendor does NOT support it: endpoints may differ or be absent on another Zephyr Scale version. Registered only because ZEPHYR_ALLOW_INTERNAL_API=true. List the custom field DEFINITIONS of a project — names, types, required flags and allowed options (GET /rest/api/2/project/{projectKey}, then GET /project/{id}/customfields/{testcase|testplan|testrun}) — so the customFields parameter of the create/update tools can be filled with valid keys and values. The public API v1 has no such endpoint…

UNOFFICIAL — internal API: this tool calls /rest/tests/1.0, the same undocumented API the Jira UI uses. The vendor does NOT support it: endpoints may differ or be absent on another Zephyr Scale version. Registered only because ZEPHYR_ALLOW_INTERNAL_API=true. List the complete folder tree of a project (GET /rest/api/2/project/{projectKey} for the numeric project id, then GET /project/{id}/foldertree/{testcase|testplan|testrun}) — the public API v1 cannot list folders at all. Each entity type has its OWN tree: test case folders are not test run folders, so a path that exists for one entity type …

Description is built at runtime.

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. Answ…

UNOFFICIAL — internal API: this tool calls /rest/tests/1.0, the same undocumented API the Jira UI uses. The vendor does NOT support it: endpoints may differ or be absent on another Zephyr Scale version. Registered only because ZEPHYR_ALLOW_INTERNAL_API=true. List the EXACT internal names of a project's execution statuses, test case statuses or test case priorities (GET /rest/api/2/project/{projectKey}, then GET /project/{id}/testresultstatus | testcasestatus | testcasepriority, falling back to GET /{segment}?projectId={id} on older builds). The public API v1 has no such endpoint, so this is th…

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.

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…

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.

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 f…

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,…

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…

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.

Description is built at runtime.

UNOFFICIAL — internal API: this tool calls /rest/tests/1.0, the same undocumented API the Jira UI uses. The vendor does NOT support it: endpoints may differ or be absent on another Zephyr Scale version. Registered only because ZEPHYR_ALLOW_INTERNAL_API=true. Link Jira issues to an EXISTING test run (cycle) — the traceability the public API cannot express at all: POST /testrun rejects an issueLinks field outright (HTTP 500 "Unrecognized field 'issueLinks' (TestRunDTO)"), so this endpoint is the only way. Resolves the run id (GET /testrun/{key}), each issue id (GET /rest/api/2/issue/{key}) and t…

UNOFFICIAL — internal API: this tool calls /rest/tests/1.0, the same undocumented API the Jira UI uses. The vendor does NOT support it: endpoints may differ or be absent on another Zephyr Scale version. Registered only because ZEPHYR_ALLOW_INTERNAL_API=true. Associate an EXISTING test run (cycle) with a test plan after creation (GET /testrun/{key} and GET /testplan/{key} for the numeric ids, GET /tracelinktype/default/testrun for the link type, then POST /tracelink/bulk/create with a flat [{ testRunId, testPlanId, typeId }] triple). The public API only accepts testPlanKey while the run is bein…

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 ba…

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.

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 = "<fromFolder>"): 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 exis…

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_ALLO…

UNOFFICIAL — internal API: this tool calls /rest/tests/1.0, the same undocumented API the Jira UI uses. The vendor does NOT support it: endpoints may differ or be absent on another Zephyr Scale version. Registered only because ZEPHYR_ALLOW_INTERNAL_API=true. Remove the items of the given test cases from an EXISTING test run (cycle) IN PLACE (GET /testrun/{key}, GET /testcase/{key}, GET /testrun/{id}/testrunitems, then PUT /testrunitem/bulk/save with deletedTestRunItems) — the run keeps its key and the surviving items keep their results. The removed items are deleted TOGETHER WITH their whole e…

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 e…

UNOFFICIAL — internal API: this tool calls /rest/tests/1.0, the same undocumented API the Jira UI uses. The vendor does NOT support it: endpoints may differ or be absent on another Zephyr Scale version. Registered only because ZEPHYR_ALLOW_INTERNAL_API=true. Reorder the items of an existing test run (cycle) IN PLACE (GET /testrun/{key}, GET /testrun/{id}/testrunitems, then PUT /testrunitem/bulk/save with updatedTestRunItemsIndexes) — the run keeps its key and every item keeps its results. Items whose test case is not listed in `order` keep their relative order AFTER the listed ones; a case pre…

Description is built at runtime.

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: <name>". 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: …

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. - Operat…

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:"/"Scenar…

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 G…

Description is built at runtime.

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 }.

UNOFFICIAL — internal API: this tool calls /rest/tests/1.0, the same undocumented API the Jira UI uses. The vendor does NOT support it: endpoints may differ or be absent on another Zephyr Scale version. Registered only because ZEPHYR_ALLOW_INTERNAL_API=true. Edit ANY test execution (result) by its numeric id, including OLDER history entries (PUT /testresult with a single-element array) — update_last_test_result reaches only the newest execution of an item. Partial update: only the fields passed are changed, and at least one is required. `status` is the case-sensitive status NAME and is resolve…

UNOFFICIAL — internal API: this tool calls /rest/tests/1.0, the same undocumented API the Jira UI uses. The vendor does NOT support it: endpoints may differ or be absent on another Zephyr Scale version. Registered only because ZEPHYR_ALLOW_INTERNAL_API=true. Rename a test run (cycle), move it to another folder or change its planned dates IN PLACE (GET /testrun/{key} for the numeric id, then PUT /testrun/{id}, then GET /testrun/{key} again to read the result back) — the run keeps its key, items and results. The public API v1 has no PUT /testrun at all. At least one field to change is required. …

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, …

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). …

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.