Zephyr Scale MCP Server

Model Context Protocol (MCP) server that integrates with Zephyr Scale test management tool for Jira. This server allows Claude Desktop and other MCP clients to fetch and update test case information directly from Zephyr Scale.

→ - Get up and running in 5 minutes

Features

• Read Operations:

  • Fetch test case information with steps, labels, details, priority, and status

  • Get complete raw test case object from API

• Write Operations:

  • Update test case labels

  • Update any test case field (objective, precondition, priority, etc.)

  • Automatic handling of mandatory fields

• Developer Friendly:

  • Support for both WSL2 and Windows environments

  • Easy integration with Claude Desktop

  • Natural language interactions in chat

Prerequisites

• Node.js (v16 or higher)

• npm or yarn

• Zephyr Scale API token

• TypeScript (included as dev dependency)

• For WSL2 users: WSL2 with Ubuntu or similar distro

Installation

1. Clone or navigate to the project directory:

cd /path/to/mcp-zephyr

2. Install dependencies:

npm install

3. Build the TypeScript code:

npm run build

Configuration

1. Get Your Zephyr Scale API Token

1. Log in to your Jira/Zephyr Scale account

2. Navigate to API token settings

3. Generate a new API token

4. Copy the token for the next step

2. Configure Claude Desktop

For detailed step-by-step instructions, see the

Edit your Claude Desktop configuration file:

• Windows: C:\Users\YourUsername\AppData\Roaming\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

WSL2 Configuration Example:

{
  "mcpServers": {
    "zephyr-steps-server": {
      "command": "wsl",
      "args": [
        "bash",
        "-c",
        "cd /home/username/mcpServers/mcp-zephyr && ZEPHYR_API_KEY='your_token' /path/to/node dist/index.js"
      ]
    }
  }
}

Windows Configuration Example:

{
  "mcpServers": {
    "zephyr-steps-server": {
      "command": "node",
      "args": ["C:\\Users\\YourUsername\\mcp-zephyr\\dist\\index.js"],
      "env": {
        "ZEPHYR_API_KEY": "your_zephyr_api_token_here"
      }
    }
  }
}

See QUICK_START.md for complete configuration examples and troubleshooting.

Usage

With Claude Desktop

Once configured in Claude Desktop, restart the application. The tools will be available for use in your chat.

Fetching Test Case Information

Ask Claude naturally:

Get the test steps for RADAR-T1

Show me test case RDR-T23 with all details

What are the labels on RADAR-T5?

Returns:

• Test case name and key

• All labels

• Objective/description

• Preconditions

• Priority and status

• Complete test steps with instructions and expected results

Updating Test Case Labels

Ask Claude to update labels:

Update labels for RADAR-T1 to: smoke-test, regression, automated

Set labels for RDR-T23 to: critical, P1

Remove all labels from RADAR-T5

Note: When updating labels, Claude will first fetch the current test case information to understand the context, then update the labels.

Updating Other Test Case Fields

For advanced updates (objective, precondition, priority, etc.):

Update the objective for RADAR-T1 to "Verify login functionality with valid credentials"

Change the priority of RDR-T23 to High

Claude will:

1. Fetch the complete test case details

2. Modify the requested fields

3. Update the test case with all mandatory fields intact

Available Tools

get_zephyr_steps

Fetches complete test case information including labels, details, and test steps from Zephyr Scale.

Input:

• testCaseKey (string): The test case ID (e.g., "RADAR-T1")

Output:

• JSON object containing:

  • testCaseKey: Test case ID

  • name: Test case name

  • labels: Array of labels assigned to the test case

  • objective: Test objective/description from Details

  • precondition: Prerequisites for the test

  • priority: Priority level

  • status: Current test case status

  • steps: Array of test steps with:

    • index: Step number

    • instruction: Step description

    • expectedResult: Expected outcome

    • testData: Test data (if applicable)

update_test_case_labels

Updates the labels for a specific test case in Zephyr Scale.

Input:

• testCaseKey (string): The test case ID (e.g., "RADAR-T1")

• labels (array of strings): List of labels to set for the test case

Output:

• Success message confirming the labels were updated

Important Notes:

• This tool REPLACES all existing labels with the new list provided

• To add a label, you must include all existing labels plus the new one

• To remove a label, provide the list without it

• To remove all labels, provide an empty array []

Example Usage:

• "Update RADAR-T1 labels to: smoke-test, regression, high-priority"

• "Set labels for RADAR-T5 to: critical, P1"

• "Remove all labels from RADAR-T10"

get_test_case_details

Fetches the complete raw test case object from Zephyr Scale API.

Input:

• testCaseKey (string): The test case ID (e.g., "RADAR-T1")

Output:

• Complete JSON object with all test case fields as returned by Zephyr API

Use Case:

• Get the full test case structure including all mandatory fields

• Useful before making updates to ensure all required fields are present

• Returns raw API response for maximum flexibility

update_test_case

Updates a test case with a complete payload to satisfy mandatory field requirements.

Input:

• testCaseKey (string): The test case ID (e.g., "RADAR-T1")

• payload (object): The complete test case object with modified fields

Output:

• Success message confirming the update

Workflow:

1. Use get_test_case_details to fetch the current test case

2. Modify the desired fields in the returned object

3. Use update_test_case with the modified object

Important Notes:

• Zephyr API requires all mandatory fields to be present in PUT requests

• This tool accepts the complete payload to avoid "missing mandatory field" errors

• Best practice: Always fetch details first, then update

Example Usage:

• "Update the objective for RADAR-T1 to 'Test login functionality'"

• "Change priority of RDR-T23 to High"

• "Update precondition for RADAR-T5"

Development

Build

Compile TypeScript to JavaScript:

npm run build

Watch Mode

Automatically recompile on changes:

npm run watch

Project Structure

mcp-zephyr/
├── dist/                # Compiled JavaScript (generated, gitignored)
│   ├── index.js         # Main MCP server (compiled)
│   └── index.d.ts       # TypeScript definitions
├── node_modules/        # Dependencies (gitignored)
├── index.ts             # Source code - MCP Server implementation
├── package.json         # Node.js dependencies and scripts
├── tsconfig.json        # TypeScript configuration
├── .gitignore           # Git ignore rules
├── QUICK_START.md       # Quick start guide (5-minute setup)
├── README.md            # Complete documentation (this file)
└── CLAUDE.md            # Claude Code project instructions

API Integration

• Base URL: https://api.zephyrscale.smartbear.com/v2

• Endpoints:

  • GET /testcases/{testCaseKey} - Fetch test case details, labels, and metadata

  • GET /testcases/{testCaseKey}/teststeps - Fetch test steps

  • PUT /testcases/{testCaseKey} - Update test case details (including labels)

• Authentication: Bearer token via Authorization header

Troubleshooting

For common issues and solutions, see the

"ZEPHYR_API_KEY environment variable is not set"

Make sure you have set the ZEPHYR_API_KEY correctly in your Claude Desktop configuration.

WSL2: Set it in the bash command: ZEPHYR_API_KEY='your_token' Windows: Set it in the env section of the config

"Server disconnected" or "Cannot attach to MCP server"

Check the logs:

C:\Users\YourUsername\AppData\Roaming\Claude\logs\mcp-server-zephyr-steps-server.log

Common causes:

• Incorrect Node.js path (WSL2 users: use full path like /home/user/.nvm/versions/node/v22.17.1/bin/node)

• Missing dist/index.js file (run npm run build)

• Invalid API token

"Cannot find module" errors

Run npm install to ensure all dependencies are installed, then rebuild:

npm install
npm run build

"node: command not found" (WSL2 only)

When using WSL2, don't use just node - use the full path to your Node.js binary:

# Find your node path
which node
# Use that full path in claude_desktop_config.json

License

ISC

Support

For issues or questions, refer to the MCP SDK documentation or Zephyr Scale API documentation.