add_test_cases_to_run
Add test cases to an existing test run (Cloud only — not supported on Data Center)
LABSCO SUMMARY
The Cloud and Data Center split is written into the tool surface, so which edition you run decides which of these calls exist for you.
delete_test_case and delete_test_run are marked Data Center; update_test_run, add_test_cases_to_run and list_executions_by_cycle are marked Cloud; create_folder, get_test_execution and search_test_runs behave differently on each. Labelling it per tool is the right call, and it does mean a workflow written against one edition will reach for calls the opposite edition does not have — worth knowing too that on Cloud, search_test_runs returns cycles sitting in the exact folder rather than descending into sub-folders. Only the Zephyr key is required: the Jira username and token matter just for issue_links on Jira Cloud, and without them a test case is still created, with a warning that the link failed.
What it is
A Zephyr Scale server against a Jira-authenticated Zephyr instance, exposing test case authoring, folder management, test run and cycle handling, execution lookup and search, with the differences between Cloud and Data Center called out per tool.
What you get
- Test case authoring: create_test_case writes STEP_BY_STEP, PLAIN_TEXT or BDD content and accepts project_key, folder, objective, precondition, priority, status, labels, owner_id, estimated_time, component_id, issue_links, parameters, custom_fields and test_script; get_test_case reads one back by test_case_key; update_test_case_bdd replaces BDD content and preserves fields you leave out.
- A way to match your project's own field structure: create_test_case points at the zephyr://testcase/EXISTING-KEY resource so a real test case can be fetched and its shape copied, custom_fields included.
- Folder handling: create_folder takes a path such as "/Parent/Child", resolving parent segments on Cloud and sending the full path on Data Center; get_folders returns the entire subtree under folder_path at every depth, or every folder matching project_key and folder_type.
- Runs and cycles: create_test_run takes test_case_keys, environment, owner, planned_start_date, planned_end_date, issue_key, test_plan_key and jira_project_version; get_test_run and get_test_run_cases read one back; update_test_run sets owner, name, description, dates or status_id on Cloud; add_test_cases_to_run appends cases on Cloud.
- Execution results: get_test_execution returns one by execution_id, with test_run_keys narrowing the search on Data Center, and list_executions_by_cycle returns execution status, executedBy and actualEndDate per case in a cycle on Cloud.
- Search: search_test_cases_by_folder takes folder_path with max_results, and search_test_runs filters on project_key and folder, with folder_id available as a direct numeric lookup that skips path resolution.
- Removal on Data Center: delete_test_case and delete_test_run.
Requirements
A Zephyr Scale instance reachable at ZEPHYR_BASE_URL and a Zephyr API key as ZEPHYR_API_KEY. JIRA_USERNAME and JIRA_API_TOKEN are optional — needed only for issue_links on Jira Cloud.
Setup effort
One command plus a key — npm install -g zephyr-scale-mcp-server, then supply credentials
USE CASES
01
Turning an acceptance criterion into a test case that fits your project's fields
Pull an existing case as a template so custom_fields line up, write the new one in the format your team uses, and refine the BDD wording afterwards.
02
Finding out what a test cycle actually did
List the executions in the cycle to see status and who ran them, then open the individual execution behind anything that failed.
03
Assembling a regression cycle before a release goes out
Collect the cases from the folder they live in, open a run with the dates and environment set, and attach the cases to it.
04
Tracking down a run when you know roughly where it lives but not its key
Browse the folder tree to locate the right branch, search runs filtered to it, then open the one you were after.
05
Reorganising where a project's test cases sit
Look at the existing tree, create the branch you need by path, and check that the new structure came out where you expected.
06
Clearing out test material that no longer applies, on Data Center
Confirm what the case or run contains before removing it, then delete it through the calls that Data Center supports.
16 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
create_folder
Create a new folder in Zephyr Scale. On Cloud: provide a path like "/Parent/Child" — the server resolves parent segments and creates the leaf folder. On Data Center: the full path is sent directly.
create_test_case
Create a new test case with STEP_BY_STEP, PLAIN_TEXT, or BDD content. To match your project's structure, use the zephyr://testcase/EXISTING-KEY resource to fetch a real test case and use its structure as a template, especially for custom_fields.
create_test_run
Create a new test run
delete_test_case
Delete a specific test case (Data Center only — not supported on Cloud v2)
delete_test_run
Delete a specific test run (Data Center only — not supported on Cloud v2)
get_folders
Get folders from Zephyr Scale. All parameters are optional. If folder_path is provided, returns the full subtree (the folder and all its descendants at every depth) under that path. Otherwise returns all folders matching the filters.
get_test_case
Get detailed information about a specific test case
get_test_execution
Get detailed information about a specific test execution by ID or key. On Cloud, provide the execution ID or key (e.g., PROJ-E123) directly. On Data Center, also provide test_run_keys to search within.
get_test_run
Get detailed information about a specific test run
get_test_run_cases
Get test case keys from a test run
list_executions_by_cycle
List all test executions for a specific test cycle. Returns execution status, executedBy, actualEndDate for each test case in the cycle. Cloud only.
search_test_cases_by_folder
Search for test cases in a specific folder
search_test_runs
Search for test runs using a query. Supports filtering by projectKey and/or folder path. On Cloud, only returns cycles in the exact folder (not sub-folders). Use folder_id for direct numeric ID lookup (skips path resolution).
update_test_case_bdd
Update an existing test case with BDD content. Optionally update the test case name. Unspecified fields are preserved.
update_test_run
Update an existing test cycle — set owner, name, description, dates, or status. Unspecified fields are preserved. Cloud only.
BEFORE YOU INSTALL
What to know first
Tools you get
16 tools when we connected. delete_test_run is undocumented and deletes data. update_test_run, add_test_cases_to_run and list_executions_by_cycle work on Jira Cloud only, leaving thirteen usable on Data Center; JIRA_TYPE overrides automatic detection.
Requires
- npx on PATH
- ZEPHYR_BASE_URL in your environment
- ZEPHYR_API_KEY in your environment
Optional
- JIRA_USERNAME in your environment
- JIRA_API_TOKEN in your environment
CONTEXT COST
Light Standing cost
Rated by the size of the 16 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Add the block to your client, or run the command directly.
Server setup
Configuration file
JSON
{
"mcpServers": {
"zephyr-server": {
"command": "npx",
"args": [
"zephyr-scale-mcp-server@latest"
],
"env": {
"ZEPHYR_BASE_URL": "https://<YOUR_COMPANY>.atlassian.net",
"ZEPHYR_API_KEY": "<YOUR_ZEPHYR_API_KEY>",
"JIRA_USERNAME": "<YOUR_JIRA_USERNAME>",
"JIRA_API_TOKEN": "<YOUR_JIRA_API_TOKEN>"
}
}
}
}https://<YOUR_COMPANY>.atlassian.net is your Jira Cloud URL, and <YOUR_ZEPHYR_API_KEY> your Zephyr Scale API key (in Jira: profile picture → Zephyr API keys). JIRA_USERNAME and JIRA_API_TOKEN are only needed for issue_links on Jira Cloud — leave both out otherwise. On Jira Data Center, keep only ZEPHYR_BASE_URL (your Jira server) and ZEPHYR_API_KEY (the Zephyr Scale token from your Jira profile).
npm
TERMINAL
npm install -g zephyr-scale-mcp-serverThen use the configuration block with "command" changed to "zephyr-scale-mcp".
