MCP Zephyr

A Model Context Protocol (MCP) server for Zephyr Scale Cloud test management. This MCP server provides tools to manage test cases, test executions, test cycles, and test plans in Zephyr Scale Cloud.

Features

• Test Case Management: Create, read, update, delete, and search test cases
• Test Execution: Execute tests and track results with detailed step-by-step outcomes
• Test Cycle Management: Organize test cases into cycles and manage execution progress
• Test Plan Management: Create and manage comprehensive test plans
• Bulk Operations: Efficiently handle multiple test executions at once
• Search and Filtering: Use JQL (Jira Query Language) for advanced test case searching

Prerequisites

• Node.js 18+
• Zephyr Scale Cloud account with API access
• Valid Zephyr API token

Installation

1. Clone this repository:

git clone <repository-url>
cd mcp-zephyr

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

Create a .env file based on .env.example:

cp .env.example .env

Edit .env with your Zephyr Scale Cloud credentials:

# 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

Getting Your API Token

1. Log into your Zephyr Scale Cloud instance
2. Navigate to Settings > API Tokens
3. Generate a new API token with appropriate permissions
4. Copy the token and add it to your .env file

Usage

Start the MCP Server

npm start

Or for development:

npm run dev

Integration with Claude Desktop

Add this server to your Claude Desktop configuration:

{
  "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

Test Case Management

zephyr_list_test_cases

List test cases in a project.

• Parameters: projectKey, maxResults, startAt

zephyr_get_test_case

Get a specific test case by key.

• Parameters: testCaseKey

zephyr_create_test_case

Create a new test case.

• Parameters: projectKey, name, objective, precondition, status, priority, component, estimatedTime, labels, steps

zephyr_update_test_case

Update an existing test case.

• Parameters: testCaseKey, plus any fields to update

zephyr_delete_test_case

Delete a test case.

• Parameters: testCaseKey

zephyr_search_test_cases

Search test cases using JQL.

• Parameters: jql, maxResults

Test Execution Management

zephyr_list_test_executions

List executions for a test cycle.

• Parameters: testCycleKey, maxResults

zephyr_get_test_execution

Get a specific test execution.

• Parameters: executionKey

zephyr_create_test_execution

Create a new test execution.

• Parameters: testCaseKey, testCycleKey, status, executedBy, actualTime, comment, defects, stepResults

zephyr_update_test_execution

Update an existing test execution.

• Parameters: executionKey, plus any fields to update

zephyr_bulk_create_test_executions

Create multiple test executions at once.

• Parameters: executions (array)

zephyr_get_test_case_executions

Get all executions for a test case.

• Parameters: testCaseKey, maxResults

zephyr_get_test_results

Get test results for a test cycle.

• Parameters: testCycleKey, maxResults

Test Cycle Management

zephyr_list_test_cycles

List test cycles in a project.

• Parameters: projectKey, maxResults

zephyr_get_test_cycle

Get a specific test cycle.

• Parameters: testCycleKey

zephyr_create_test_cycle

Create a new test cycle.

• Parameters: projectKey, name, description, status, environment, startDate, endDate

zephyr_update_test_cycle

Update an existing test cycle.

• Parameters: testCycleKey, plus any fields to update

zephyr_add_test_cases_to_cycle

Add test cases to a test cycle.

• Parameters: testCycleKey, testCaseKeys (array)

zephyr_remove_test_cases_from_cycle

Remove test cases from a test cycle.

• Parameters: testCycleKey, testCaseKeys (array)

Test Plan Management

zephyr_list_test_plans

List test plans in a project.

• Parameters: projectKey, maxResults

zephyr_get_test_plan

Get a specific test plan.

• Parameters: testPlanKey

zephyr_create_test_plan

Create a new test plan.

• Parameters: projectKey, name, description, status, startDate, endDate

zephyr_update_test_plan

Update an existing test plan.

• Parameters: testPlanKey, plus any fields to update

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
    }
  ]
});

Creating a Test Execution

await zephyr_create_test_execution({
  testCaseKey: "PROJ-T1",
  testCycleKey: "PROJ-C1",
  status: "Pass",
  executedBy: "test.user@company.com",
  actualTime: 5,
  comment: "All steps executed successfully",
  stepResults: [
    {
      stepIndex: 0,
      status: "Pass",
      actual: "Login page loaded correctly"
    },
    {
      stepIndex: 1,
      status: "Pass",
      actual: "Credentials accepted"
    },
    {
      stepIndex: 2,
      status: "Pass",
      actual: "Successfully redirected to dashboard"
    }
  ]
});

Searching Test Cases

await zephyr_search_test_cases({
  jql: "project = PROJ AND status = 'Draft' AND priority = High",
  maxResults: 25
});

Error Handling

The server provides detailed error messages for common issues:

• Authentication errors: Invalid API token
• Authorization errors: Insufficient permissions
• Validation errors: Invalid input data
• Network errors: Connection issues
• API limits: Rate limiting exceeded

Development

Project Structure

src/
├── index.ts                 # Main MCP server entry point
├── zephyr-client.ts        # Zephyr API client
├── types.ts                # TypeScript type definitions
└── tools/                  # MCP tool implementations
    ├── test-case-tools.ts
    ├── test-execution-tools.ts
    ├── test-cycle-tools.ts
    └── test-plan-tools.ts

Building

npm run build

Testing

npm run dev

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues related to:

• This MCP server: Create an issue in this repository
• Zephyr Scale Cloud: Contact SmartBear support
• MCP protocol: See Model Context Protocol documentation

Changelog

v1.0.0

• Initial release
• Full test case management
• Test execution tracking
• Test cycle and plan management
• Bulk operations support
• JQL search functionality