zephyr-squad-server-mcp

zephyr-squad-server-mcp

An MCP server that lets an AI agent drive Zephyr for Jira — Server / Data Center (ZAPI), the test-management suite for Jira. It exposes the most common test-management operations (cycles, folders, executions, test steps, step results, ZQL search) as well-described tools over stdio, so it plugs into Claude Desktop, Claude Code, and any other MCP client.

This targets the Server/DC flavor (/rest/zapi/latest). It is not for Zephyr Squad Cloud, which uses a different JWT-signed API.

Install

The server is published on PyPI and is easiest to run with uv:

uvx zephyr-squad-server-mcp        # run directly, no install
# or
uv tool install zephyr-squad-server-mcp
# or, in a venv
pip install zephyr-squad-server-mcp

Configuration

The connection rides on your Jira instance's authentication (shared by ZAPI and the Jira core REST API). Configure via environment variables or a .env file (see .env.example):

| Variable | Required | Default | Description | |---|---|---|---| | JIRA_URL | ✅ | — | Jira base URL, e.g. https://jira.company.com (no /rest suffix). | | JIRA_PERSONAL_TOKEN | one of | — | Personal Access Token → Authorization: Bearer … (recommended for DC). | | JIRA_USERNAME + JIRA_PASSWORD | one of | — | Basic-auth fallback (password or API token). Used only if JIRA_PERSONAL_TOKEN is empty. | | ZEPHYR_API_PATH | | /rest/zapi/latest | ZAPI base path on the Jira host. | | ZEPHYR_TIMEOUT | | 30 | Per-request timeout (seconds). | | ZEPHYR_VERIFY_SSL | | true | Verify TLS certs. Set false only for trusted internal self-signed hosts. |

The server fails fast with a clear error if the base URL or authentication is missing.

Client configuration (stdio)

Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json or Claude Code .mcp.json):

{
  "mcpServers": {
    "zephyr-squad": {
      "command": "uvx",
      "args": ["zephyr-squad-server-mcp"],
      "env": {
        "JIRA_URL": "https://jira.company.com",
        "JIRA_PERSONAL_TOKEN": "your-personal-access-token"
      }
    }
  }
}

For local development against a checkout, point command at uv:

{
  "mcpServers": {
    "zephyr-squad": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/zephyr-squad-server-mcp", "zephyr-squad-server-mcp"],
      "env": { "JIRA_URL": "https://jira.company.com", "JIRA_PERSONAL_TOKEN": "…" }
    }
  }
}

Tools

All id-bearing tools accept either a numeric id or a human-friendly key/name for project (key like SONY or its name), version (name like Version 1.0, or -1/Unscheduled), and issue (key like SONY-1386). Resolved ids are cached for the session, so the first call does the lookup and later calls reuse it.

Full reference: see docs/tools.md for every tool's arguments, types, defaults, the exact ZAPI endpoint it calls, and sync/async behavior. The table below is a quick index.

| Tool | What it does | |---|---| | list_cycles | List test cycles for a project/version. | | get_cycle | Get one cycle's details (id -1 = the Ad hoc cycle). | | create_cycle | Create a test cycle. | | update_cycle | Update a cycle's fields (id is sent in the body). | | delete_cycle | Delete a cycle (async; auto-polls to completion by default). | | export_cycle | Get a CSV download link for a cycle's executions. | | copy_executions_to_cycle | Copy executions into a cycle (async; auto-polls to completion by default). | | move_executions_to_folder | Move executions from a cycle into a folder (async; auto-polls to completion by default). | | list_cycle_folders | List folders within a cycle. | | create_folder | Create a folder under a cycle. | | update_folder | Update a folder's name/description. | | delete_folder | Delete a folder from a cycle (async; auto-polls to completion by default). | | list_executions | List executions in a cycle (optionally a folder). | | update_execution | Set an execution's status (PASS/FAIL/WIP/BLOCKED/…). | | list_test_steps | List the test steps of a test issue. | | create_test_step | Add a test step to a test issue. | | list_step_results | List per-step results for an execution. | | search_executions | Run a ZQL query and return matching executions. | | get_execution_status_counts | Status-count rollup for a project/version (by cycle). | | get_execution_status_counts_by_assignee | Per-assignee status counts for cycle(s). | | list_executions_by_issue | A single test's executions across all cycles. | | list_execution_defects | Defects linked to an execution. | | get_tests_by_requirement | Tests covering requirement(s); flags orphans. | | get_executions_by_test | Executions for a test (coverage history). | | get_executions_by_defect | Executions linked to a defect. | | get_defect_statistics | Per-defect execution/req/test rollups. | | update_test_step | Edit a test step's action/data/result. | | delete_test_step | Delete a test step. | | create_execution | Schedule a test into a cycle. | | add_tests_to_cycle_from_list | Bulk-add an explicit list of tests to a cycle as new UNEXECUTED executions (async). | | add_tests_to_cycle_from_filter | Bulk-add tests matched by a saved ZQL filter to a cycle as new UNEXECUTED executions (async). | | add_tests_to_cycle_from_cycle | Add tests from another cycle as new UNEXECUTED executions (async). | | update_step_result | Set a step result's status/comment. | | link_execution_defects | Link Jira defects to executions (async). | | assign_execution | Assign an execution to a user. | | delete_execution | Delete an execution by id. | | get_job_progress (helper) | Manually poll any async job by token. | | list_projects (helper) | List projects (name → id discovery). | | list_versions (helper) | List a project's versions (name → id discovery). | | get_zephyr_test_issue_type (helper) | Discover the Zephyr Test issue-type id per project (use case 1.1). |

Dates use Jira's dd/MMM/yy format (e.g. 4/Dec/12). Execution-status codes: -1=UNEXECUTED, 1=PASS, 2=FAIL, 3=WIP, 4=BLOCKED, 5=PENDING, 6=APPROVED, 7=CANCELLED.

Development

uv sync                  # create venv + install deps (incl. dev group)
uv run pytest            # unit tests (httpx mocked with respx — no live Jira needed)
uv run ruff check        # lint
uv run mcp dev src/zephyr_squad_server_mcp/server.py   # MCP Inspector smoke test

docs/getzephyr.apib is the ZAPI API Blueprint used as the reference for request/response shapes during development. It was retrieved from the official public documentation at <https://getzephyr.docs.apiary.io/> (© SmartBear Software). An older version is also available in the zfjdeveloper/zapi-docs repository.

The Inspector (mcp dev) launches the MCP Inspector via npx, so it needs Node.js / npx on your PATH. The tool list loads without any Jira config, but invoking a tool builds the client on first use — so set JIRA_URL and auth (a .env is read automatically) before running tools.

Publishing to PyPI

uv build                                  # produces wheel + sdist in dist/
uv publish --token "$UV_PUBLISH_TOKEN"    # or set UV_PUBLISH_TOKEN in the env

Test against TestPyPI first:

uv publish --publish-url https://test.pypi.org/legacy/ --token "$TESTPYPI_TOKEN"

License

MIT — see LICENSE.