Zephyr Scale MCP

An MCP (Model Context Protocol) server that connects AI assistants to Zephyr Scale Cloud test management. Ask natural language questions about your test suite and get instant, structured answers.

Who is this for?

Role	What you can ask
Product Manager	"How many test cases do we have for the 4.2 release?"
Product Owner	"What tests cover the authentication feature?"
QA Lead	"Show me the full test suite hierarchy for our project"
Developer	"Find all test cases related to login validation"
Engineering Manager	"What's the pass/fail status of the latest test cycle?"

Tools

Tool	Description	Best for
list_projects	Discover available projects	Everyone — start here
get_folder_tree_with_counts	Full hierarchy with TC counts per folder	QA Leads, PMs
search_test_cases	Keyword search across all test case fields	Developers, QA
get_test_case	Full details + test steps for one test case	QA Engineers
get_test_cases_in_folder	Browse a specific test suite	QA Leads
get_release_summary	Coverage summary for a release or feature area	PMs, POs
get_test_cycles	List test execution cycles	QA Leads, PMs
get_test_execution_stats	Pass/fail/blocked breakdown for a cycle	QA Leads, PMs
find_tests_linked_to_jira	Test cases linked to a Jira story or bug	PMs, POs, QA
search_test_cycles	Find cycles by name keyword	QA Leads, PMs
get_test_cycle_scenario_map	Coverage heatmap — which features a cycle tested	QA Leads, Eng Managers
get_cycles_covering_scenario	Which cycles have run tests for a scenario	QA Leads, PMs

Quick Start

Prerequisites

• A Zephyr Scale Cloud subscription
• A Zephyr Scale API token (see below)
• Your Jira Cloud instance URL (e.g. https://yourcompany.atlassian.net)

Getting your API Token

1. Log in to your Jira instance
2. Go to Apps → Zephyr Scale → API Access Tokens
3. Click Create Access Token and copy it

Option 1: Docker (recommended)

docker run -i --rm \
  -e ZEPHYR_API_TOKEN=your_token \
  -e JIRA_BASE_URL=https://yourcompany.atlassian.net \
  prevalent-ai/zephyr-mcp

Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "zephyr_scale": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "ZEPHYR_API_TOKEN",
        "-e", "JIRA_BASE_URL",
        "prevalent-ai/zephyr-mcp"
      ],
      "env": {
        "ZEPHYR_API_TOKEN": "your_zephyr_api_token",
        "JIRA_BASE_URL": "https://yourcompany.atlassian.net"
      }
    }
  }
}

Option 2: Python (local)

git clone https://github.com/prevalent-ai/zephyr-mcp
cd zephyr-mcp
python -m venv .venv
source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Create a .env file:

ZEPHYR_API_TOKEN=your_zephyr_api_token
JIRA_BASE_URL=https://yourcompany.atlassian.net

Claude Desktop config:

{
  "mcpServers": {
    "zephyr_scale": {
      "command": "/path/to/.venv/bin/python",
      "args": ["/path/to/zephyr-mcp/server.py"]
    }
  }
}

Example Conversations

You: What projects have test cases in Zephyr?
AI:  [calls list_projects()]
     Found 8 projects: PROJ, APP, QA, INFRA, ...

You: Show me the test suite structure for the APP project
AI:  [calls get_folder_tree_with_counts("APP")]
     APP has 3,200 test cases across 180 folders.
     Top areas: Authentication (320), API Tests (280), UI Regression (240)...

You: How many tests do we have for the 4.2 release?
AI:  [calls get_release_summary("APP", "4.2")]
     Found 12 folders matching '4.2' with 245 test cases total.
     DevOps: 62 | Backend: 89 | Frontend: 47 | Integration: 47

You: Are we ready to ship? What's the test cycle status?
AI:  [calls get_test_cycles("APP"), get_test_execution_stats("APP-R15")]
     Cycle 'APP 4.2 Regression': 245 total, 198 executed (80.8%)
     PASS: 172 | FAIL: 18 | BLOCKED: 8 | NOT_EXECUTED: 47

You: Find all test cases related to password reset
AI:  [calls search_test_cases("password reset", project_key="APP")]
     Found 14 matching test cases:
     APP-T201: Verify password reset email is sent...
     APP-T202: Validate reset link expiry after 24 hours...

You: What tests cover Jira story APP-892?
AI:  [calls find_tests_linked_to_jira("APP-892")]
     3 test cases linked: APP-T201, APP-T202, APP-T450

Architecture

AI Assistant (Claude, etc.)
        │ MCP protocol (stdio)
        ▼
    server.py  ←── 12 tools
        │
        ▼
  zephyr_client.py
        │ HTTPS + Bearer JWT
        ▼
api.zephyrscale.smartbear.com/v2

Search strategy: Zephyr Scale has no native full-text search API. The MCP fetches test cases in batches (500/call) and filters client-side using AND logic across all text fields. Folder hierarchy counts use concurrent async calls for speed.

Environment Variables

Variable	Required	Description
ZEPHYR_API_TOKEN	Yes	Zephyr Scale Cloud API JWT token
JIRA_BASE_URL	Yes	Your Jira Cloud URL, e.g. https://yourcompany.atlassian.net

Contributing

Pull requests welcome. Please open an issue first for significant changes.

License

MIT — see LICENSE