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):

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.

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.