zephyr-scale-mcp

MCP server for Zephyr Scale on self-hosted Jira Server / Data Center — gives AI agents (Claude Code, Claude Desktop, Cursor and any other MCP client) full control over your test management: test cases, folders, test cycles, executions, test plans, attachments and automation — through the Zephyr Scale REST API v1 (/rest/atm/1.0).

Русская версия →

⚠️ This server targets Zephyr Scale Server / Data Center (formerly TM4J). Zephyr Scale Cloud (API v2) and Zephyr Squad are different APIs and are out of scope.

Why

Most Zephyr MCP servers target the Cloud API. If your Jira lives on-premise, you are stuck — and the Server/DC API v1 has real teeth: test cycles are immutable after creation, folders can't be listed, statuses are case-sensitive internal names, BDD scripts reject Feature: headers, and older plugin builds are missing whole endpoints. This server knows all of that:

• 43 tools covering the complete test-management lifecycle, each with an LLM-friendly description that encodes the API's constraints and pitfalls;
• Composite tools for the API's blind spots — add_test_steps safely merges steps (read → merge by id → write), recreate_test_run_with_items works around cycle immutability (optionally carrying the last results over), clone_test_case, get_issue_test_coverage, get_test_run_summary;
• Graceful degradation on older plugin builds — automatic fallback when the paginated results endpoint is missing, verified against a real 2018-era TM4J instance;
• Production-grade plumbing — retries with Retry-After, exponential backoff for GET, strict zod validation, typed error messages with actionable hints, secrets never reach logs or tool output, read-only mode;
• 178 unit & contract tests (vitest + msw) plus a gated end-to-end smoke scenario.

Quick start

Requirements: Node.js ≥ 20, Jira Server/DC with the Zephyr Scale plugin, a Personal Access Token (Jira 8.14+) or username/password.

No cloning needed — the package is on npm. Wire it into Claude Code:

claude mcp add zephyr-scale \
  --env JIRA_BASE_URL=https://jira.example.com \
  --env JIRA_PAT=<personal access token> \
  --env ZEPHYR_DEFAULT_PROJECT_KEY=PROJ \
  --env ZEPHYR_ALLOW_INTERNAL_API=true \
  -- npx -y zephyr-scale-mcp

or Claude Desktop / any MCP client (claude_desktop_config.json / .mcp.json):

{
  "mcpServers": {
    "zephyr-scale": {
      "command": "npx",
      "args": ["-y", "zephyr-scale-mcp"],
      "env": {
        "JIRA_BASE_URL": "https://jira.example.com",
        "JIRA_PAT": "<personal access token>",
        "ZEPHYR_DEFAULT_PROJECT_KEY": "PROJ",
        "ZEPHYR_ALLOW_INTERNAL_API": "true"
      }
    }
  }
}

git clone https://github.com/vilaabo/zephyr-scale-mcp.git
cd zephyr-scale-mcp
npm install
npm run build        # → dist/index.js

Then ask your agent to run health_check — it verifies connectivity, credentials and that the Zephyr plugin answers.

💡 ZEPHYR_ALLOW_INTERNAL_API=true is optional but highly recommended. It unlocks the things the public API simply cannot do: listing the whole folder tree (get_folder_tree), deleting folders (delete_folder) and discovering the exact case/execution status names the API silently expects (get_status_options). These tools call the same internal endpoints the Jira UI itself uses, but the vendor does not support them — drop the flag if that trade-off is not for you.

Things you can ask your agent to do

• "Create a folder /Regression/Payments and add step-by-step test cases for the checkout flow described in this document"
• "Find all Draft cases in /Regression, review them and mark the ready ones Approved"
• "Create a test cycle for sprint 42 with all smoke cases, then record the results from this report"
• "Which test cases cover issue PROJ-123 and when did they last pass?"
• "Add two steps to PROJ-T55 after step 3" — existing steps survive, guaranteed
• "Recreate cycle PROJ-R7 with three more cases, keep the results, delete the old one"

Configuration

Secrets (JIRA_PAT, JIRA_PASSWORD) never appear in logs, tool output or error messages.

Tools

Server/DC API v1 — what this server protects you from

1. Cycles are immutable. No PUT /testrun exists: you cannot rename a cycle or change its cases. The item list is set only at creation — recreate_test_run_with_items is the escape hatch.
2. Folders are never auto-created and cannot be listed publicly; renaming needs a numeric id (returned by create_folder, or use get_folder_tree).
3. owner / executedBy / assignedTo take a Jira user key (JIRAUSER10000) — not a username, not an e-mail. find_jira_user resolves it.
4. TQL is strict: mandatory spaces around operators, double-quoted strings, AND only. Cycles are searchable only by projectKey and folder.
5. Statuses/priorities are case-sensitive internal names. The UI shows localized labels for the built-ins (Draft may render as something else in your language) while custom statuses use their literal names — get_status_options shows the truth.
6. BDD scripts are the scenario body only — bare Given/When/Then/And/But lines. Texts wrapped in Feature:/Scenario: headers are rejected with 400 Invalid BDD Script; the wrapper is generated on export.
7. Step editing is id-based sync: on PUT, steps without an id are created, steps with an id updated, and existing steps missing from the list are deleted. add_test_steps handles the read-merge-write for you.
8. Deprecated API fields (issueKey, executionDate, userKey) are intentionally not accepted.

Older plugin builds (tested against a real legacy instance)

• Cycle keys may use the -C prefix (PROJ-C34) instead of -R — handled transparently.
• GET /testrun/{key}/testresults/page may not exist — the server automatically falls back to the flat endpoint and paginates client-side (the response carries a note).
• A result's overall status may be ignored when sent together with scriptResults — send the step results first, then set the overall status via update_last_test_result.
• POST /testcase/link-issues may answer 500 — link through update_test_case with issueLinks instead.
• The custom automation-results format may be strictly validated: {"version": 1, "executions": [{"source", "result", "testCase": {"key"}}]} works, while extra per-execution fields (e.g. executionTime) are rejected with Invalid Custom Format JSON file. Cucumber JSON reports (scenario tagged @TestCaseKey=PROJ-T1) work as-is.
• POST /testcase/bulk may answer HTTP 500 with an empty body for any payload while single creation works — create_test_cases_bulk detects this and automatically falls back to creating the cases one by one, reporting which items succeeded (#1).

Development

npm run typecheck    # tsc --noEmit (strict)
npm test             # 178 unit + contract tests (vitest + msw), no network
npm run smoke        # end-to-end scenario against a real instance (ZEPHYR_E2E=1)

src/
├── index.ts        # bootstrap: config, tool registration, stdio transport
├── config.ts       # env validation
├── http.ts         # fetch wrapper: auth, timeouts, retries, error normalization
├── schemas.ts      # shared zod schemas (steps, scripts, result fields, TQL help)
├── toolkit.ts      # defineTool(): strict input, read-only guard, response shaping
├── runResults.ts   # results pagination with legacy fallback
└── tools/          # testCases, folders, testRuns, testResults, testPlans,
                    # attachments, automation, runMaintenance, misc

Stdout is reserved for the MCP protocol; all logging goes to stderr.

License

MIT