Zephyr Scale MCP Server

Model Context Protocol server for Zephyr Scale test management, supporting both Jira Cloud and Data Center. Create, read, and manage test cases through the Atlassian REST API with official API-compliant schemas. Access live test case data, example payloads, and file resources through a unified resource system.

Features

• ✅ Jira Cloud & Data Center Support: Seamlessly connects to both Jira Cloud (using API v2) and self-hosted Data Center instances (using API v1) with automatic configuration detection.
• ✅ Official API-Compliant Schemas: Tools and data structures match the official Zephyr Scale REST API, ensuring compatibility and reliability.
• ✅ Unified Test Case Creation: A single create_test_case tool handles all script types (BDD, Step-by-Step, Plain Text) for a simplified workflow.
• ✅ Full Test Lifecycle Management: Comprehensive tools to create, read, delete test cases, and manage test runs, executions, and folders.
• ✅ Live Templating System: Use real test cases from your Zephyr instance as templates (zephyr://testcase/KEY) to ensure consistency and correct project-specific fields.
• ✅ Unified Resource System: Access live Zephyr data, local files (file://), and built-in examples through a consistent URI-based system.

Installation and Configuration

You can run the server using npx without installation, or install it globally from npm.

Using npx (Recommended)

Configure your MCP client with the following structure.

Jira Cloud:

{
  "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-email@company.com",
        "JIRA_API_TOKEN": "your-jira-api-token"
      }
    }
  }
}

Note: JIRA_USERNAME and JIRA_API_TOKEN are optional but required if you want to use the issue_links field when creating test cases. Without them, issue linking will fail with a 401 warning (the test case is still created). Generate a Jira API token at id.atlassian.com/manage-profile/security/api-tokens.

Jira Cloud (EU region):

{
  "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-email@company.com",
        "JIRA_API_TOKEN": "your-jira-api-token",
        "ZEPHYR_API_BASE_URL": "https://eu.api.zephyrscale.smartbear.com/v2"
      }
    }
  }
}

Jira Data Center:

{
  "mcpServers": {
    "zephyr-server": {
      "command": "npx",
      "args": ["zephyr-scale-mcp-server@latest"],
      "env": {
        "ZEPHYR_BASE_URL": "https://your-jira-server.com",
        "ZEPHYR_API_KEY": "your-api-token"
      }
    }
  }
}

Using global npm installation

First install the package globally:

npm install -g zephyr-scale-mcp-server

Then, update the command in your MCP configuration to "command": "zephyr-scale-mcp".

Core Concepts

Unified API

The latest version features a unified create_test_case tool that supports all test script types (STEP_BY_STEP, PLAIN_TEXT, and BDD) through a single, consistent interface. This matches the official Zephyr Scale REST API v1 structure exactly, simplifying the test creation process.

Jira Cloud vs. Data Center

The server automatically detects your Jira environment and uses the appropriate API version:

• Jira Cloud: Uses Zephyr Scale API v2.
• Jira Data Center: Uses Zephyr Scale API v1.

Some tools are platform-specific. For example, add_test_cases_to_run is only available on Cloud, as the Data Center API (v1) does not support modifying test runs after creation.

Resource System

The server provides access to various resources through URI schemes:

• zephyr://testcase/YOUR-TEST-CASE-KEY: Fetch real test case data from your Zephyr instance to use as templates.
• file:///absolute/path/to/your/file.json: Read user-provided files.
• zephyr://examples/...: Access built-in example payloads.

Tools Reference

Test Case Management

• get_test_case: Get detailed information about a specific test case.
• create_test_case: Create test cases with STEP_BY_STEP, PLAIN_TEXT, or BDD content.
• delete_test_case: Delete a specific test case.
• update_test_case_bdd: Update an existing test case with BDD content (optionally update the test case name).

Test Run Management

• create_test_run: Create a new test run.
• get_test_run: Get detailed information about a specific test run.
• get_test_run_cases: Get test case keys from a test run.
• add_test_cases_to_run: Add test cases to an existing test run. (Cloud only)

Test Execution & Search

• get_test_execution: Get detailed individual test execution results.
• search_test_cases_by_folder: Search for test cases in a specific folder.
• search_test_runs: Search for test runs by project key and/or folder path.

Organization

• create_folder: Create a new folder in Zephyr Scale.

Usage Examples

Create a BDD Test Case with Issue Links

{
  "project_key": "PROJ",
  "name": "User Authentication",
  "test_script": {
    "type": "BDD",
    "text": "Given a user with valid credentials\nWhen the user attempts to log in\nThen the user should be authenticated successfully"
  },
  "issue_links": ["PROJ-123", "PROJ-456"]
}

Note: issue_links requires JIRA_USERNAME and JIRA_API_TOKEN to be set (Cloud only). Link failures are reported as warnings — the test case is still created.

Use a Live Test Case as a Template

1. Fetch an existing test case: zephyr://testcase/PROJ-T123
2. Copy its structure (especially customFields and folder).
3. Create a new test case using the same project-specific configuration.

Create a Test Run

{
  "project_key": "PROJ",
  "name": "Sprint 1 Test Run",
  "test_case_keys": ["PROJ-T123", "PROJ-T124", "PROJ-T125"]
}

Update an Existing BDD Test Case

{
  "test_case_key": "PROJ-T123",
  "name": "Ensure the axial-flow pump is enabled",
  "bdd_content": "Feature: Pump Enablement\n\nScenario: Enable the pump\n  Given the system is powered on\n  When the operator enables the axial-flow pump\n  Then the pump should report as enabled"
}

Note: The server will convert markdown-style BDD into Gherkin when possible and will preserve all other existing test case fields.

Authentication

Jira Cloud Configuration

Variable	Required	Description
ZEPHYR_BASE_URL	✅	Your Jira Cloud URL, e.g. https://your-company.atlassian.net
ZEPHYR_API_KEY	✅	Zephyr Scale API key (JWT). Generate in Jira: profile picture (bottom left) → Zephyr API keys
JIRA_USERNAME	⚠️ Optional*	Your Jira account email address
JIRA_API_TOKEN	⚠️ Optional*	Jira API token. Generate at id.atlassian.com/manage-profile/security/api-tokens
ZEPHYR_API_BASE_URL	Optional	Override the Zephyr API base URL (e.g. for EU: https://eu.api.zephyrscale.smartbear.com/v2). Defaults to US endpoint.
JIRA_TYPE	Optional	Force "cloud" or "datacenter" — overrides auto-detection

* JIRA_USERNAME + JIRA_API_TOKEN: Required only for the issue_links feature on Cloud. The Zephyr API key cannot authenticate against the Jira REST API, so a separate Jira credential is needed to resolve issue keys to numeric IDs. Without these, issue_links will fail with a 401 warning — the test case is still created successfully.

Jira Data Center Configuration

Variable	Required	Description
ZEPHYR_BASE_URL	✅	Your Jira server URL, e.g. https://your-jira-server.com
ZEPHYR_API_KEY	✅	Zephyr Scale API token from your Jira profile settings
JIRA_TYPE	Optional	Set to "datacenter" to override auto-detection

Automatic Detection

The server automatically detects your Jira type based on ZEPHYR_BASE_URL — URLs containing .atlassian.net are treated as Cloud, everything else as Data Center. Override with JIRA_TYPE="cloud" or JIRA_TYPE="datacenter".

License

MIT