Zephyr

Zephyr MCP Server lets you manage Zephyr Scale Cloud test artifacts through the Model Context Protocol. You can create, read, update, and delete test cases; run and track test executions; organize work into test cycles; and compose comprehensive test plans, all via a cohesive MCP interface that supports bulk operations and advanced search.

How to use

You interact with the Zephyr MCP Server using an MCP client. The server exposes a set of named commands (endpoints) for test case management, test execution management, test cycle management, and test plan management. You can perform create/read/update/delete operations, search with advanced filters, and bulk-create executions. Each command is invoked through the MCP client with the appropriate tool name and parameters, and you receive structured responses that indicate success or provide the requested data.

How to install

Prerequisites you need before installing: Node.js 18+ and a Zephyr Scale Cloud account with API access. You also need a valid Zephyr API token.

# Step 1: Clone the MCP server repository
git clone <repository-url>
cd mcp-zephyr

# Step 2: Install dependencies
npm install

# Step 3: Build the project
npm run build

Configuration and usage notes

Create a configuration file based on the provided example, and set your Zephyr credentials so the MCP server can authenticate with Zephyr Scale Cloud.

dcp .env.example .env

# Required: Your Zephyr API token
ZEPHYR_API_TOKEN=your_api_token_here

# Optional: Base URL (defaults to official Zephyr Scale Cloud API)
ZEPHYR_BASE_URL=https://api.zephyrscale.smartbear.com/v2

# Optional: Default project key
ZEPHYR_PROJECT_KEY=your_project_key_here

Start the MCP server

Run the server in normal mode for production use or in development mode for debugging.

npm start

npm run dev

Integration with Claude Desktop

To connect Claude Desktop, add the Zephyr MCP server configuration to your Claude Desktop client.

{
  "mcpServers": {
    "zephyr": {
      "command": "node",
      "args": ["/path/to/mcp-zephyr/dist/index.js"],
      "env": {
        "ZEPHYR_API_TOKEN": "your_api_token_here",
        "ZEPHYR_BASE_URL": "https://api.zephyrscale.smartbear.com/v2",
        "ZEPHYR_PROJECT_KEY": "your_project_key_here"
      }
    }
  }
}

Available tools and endpoints

The MCP server exposes a comprehensive set of tools for working with Zephyr Scale Cloud data. You can manage test cases, test executions, test cycles, and test plans, including bulk operations and JQL-based searches.

Examples

Creating a Test Case

await zephyr_create_test_case({
  projectKey: "PROJ",
  name: "User Login Test",
  objective: "Verify users can successfully log in with valid credentials",
  precondition: "User must have valid account",
  status: "Draft",
  priority: "High",
  steps: [
    { action: "Navigate to login page", expected: "Login page is displayed", stepIndex: 1 },
    { action: "Enter valid username and password", expected: "Fields accept input", stepIndex: 2 },
    { action: "Click login button", expected: "User is redirected to dashboard", stepIndex: 3 }
  ]
});

Error Handling

The server provides detailed error messages for common issues such as authentication problems, insufficient permissions, invalid input data, network issues, or API rate limits.

Development

Project structure and building steps help you understand how the MCP server is organized and how to extend it.

npm run build

npm run dev

Notes

This guide covers practical setup, configuration, and usage patterns to help you start automating Zephyr Scale Cloud workflows through MCP.

Available tools

zephyr_list_test_cases

List test cases in a project with pagination and optional filters.

zephyr_get_test_case

Retrieve details for a single test case by its key.

zephyr_create_test_case

Create a new test case with metadata, steps, and attributes.

zephyr_update_test_case

Update fields for an existing test case.

zephyr_delete_test_case

Delete a test case by its key.

zephyr_search_test_cases

Search test cases using a JQL-like query with optional max results.

zephyr_list_test_executions

List executions for a specific test cycle with paging.

zephyr_get_test_execution

Get details of a single test execution.

zephyr_create_test_execution

Create a new test execution for a test case and cycle with status and results.

zephyr_update_test_execution

Update an existing test execution with new status or results.

zephyr_bulk_create_test_executions

Create multiple test executions in a single operation.

zephyr_get_test_case_executions

Fetch all executions related to a particular test case.

zephyr_get_test_results

Retrieve results for a test cycle across executions.

zephyr_list_test_cycles

List all test cycles for a project with paging.

zephyr_get_test_cycle

Get details of a specific test cycle.

zephyr_create_test_cycle

Create a new test cycle with metadata including date range.

zephyr_update_test_cycle

Update fields for an existing test cycle.

zephyr_add_test_cases_to_cycle

Add one or more test cases to a test cycle.

zephyr_remove_test_cases_from_cycle

Remove test cases from a test cycle.

zephyr_list_test_plans

List test plans within a project with paging.

zephyr_get_test_plan

Retrieve a specific test plan by key.

zephyr_create_test_plan

Create a new test plan with metadata and schedule.

zephyr_update_test_plan

Update fields for an existing test plan.