Zephyr Scale

You set up and run a dedicated MCP server that connects to Zephyr Scale’s REST API to automate test management workflows. This server exposes a complete set of endpoints you can invoke through any MCP-compatible client, supports regional API endpoints, handles authentication via tokens, and provides robust logging and error handling for reliable automation.

How to use

You will run the MCP server locally and connect to it from your MCP client or Claude Desktop. Start the server in a dedicated environment, ensure you provide your Zephyr Scale API token, and configure the client to point to the server either via HTTP or by starting the local MCP process. Use the available tools to list, create, update, and organize test cases, folders, cycles, executions, environments, and other Zephyr Scale resources. Leverage the token-based authentication to access Zephyr Scale data and ensure your client respects region settings for Global or EU endpoints.

How to install

Prerequisites: Python 3.8 or newer. A Zephyr Scale account with API access. A Jira instance connected to Zephyr Scale. A valid Zephyr Scale API token.

# 1. Create project directory
mkdir zephyr-scale-mcp
cd zephyr-scale-mcp

# 2. Initialize UV project
uv init

# 3. Save the MCP server script file in this directory (e.g., zephyr_mcp_server.py)

Install dependencies with UV to enable the MCP server functionality.

uv add fastmcp python-dotenv httpx

Configuration

Generate a Zephyr Scale API token from your Jira instance and prepare an environment file to supply your token and region preference to the MCP server.

# Required: Your Zephyr Scale API token
ZEPHYR_API_TOKEN=your_jwt_token_here

# Optional: Set to true for EU region (default: false)
ZEPHYR_USE_EU_REGION=false

Test configuration by starting the MCP server locally.

uv run python zephyr_mcp_server.py

Setup with Claude Desktop

To integrate with Claude Desktop, you can run the MCP server with UV in a local workspace and point Claude to the local process. The first option runs a separate app entry, while the second uses the main MCP server file with environment variables.

{
  "mcpServers": {
    "zephyr-scale-app": {
      "command": "uv",
      "args": ["run", "python", "app.py"],
      "cwd": "/path/to/your/zephyr-scale-mcp",
      "env": {
        "ZEPHYR_API_TOKEN": "your_jwt_token_here",
        "ZEPHYR_USE_EU_REGION": "false"
      }
    }
  }
}

Alternative setup using the main MCP server script and a .env file is recommended for simplicity.

{
  "mcpServers": {
    "zephyr-scale-mcp": {
      "command": "uv",
      "args": ["run", "python", "zephyr_mcp_server.py"],
      "cwd": "/path/to/your/zephyr-scale-mcp"
    }
  }
}

After configuring Claude Desktop, restart the application to load Zephyr Scale tools into your workflow. The available tools provide full interaction with test cases, cycles, environments, and other entities.

Available tools and usage patterns

The MCP server exposes a comprehensive set of tools to manage Zephyr Scale resources. You can list, fetch, create, update, and link items across test cases, folders, cycles, executions, projects, priorities, statuses, environments, links, issue associations, and utilities.

Error handling

The server provides detailed HTTP status codes and messages for authentication, validation, and network issues. It gracefully handles JSON parsing errors and includes retry logic for rate limits. If you encounter an error, review the status code, error message, and any accompanying detail to adjust your client requests or token configuration.

Security considerations

Store API tokens securely in environment variables. Use .env files for local development and consider secrets management in production. Rotate tokens regularly and monitor access logs to detect unusual activity.

Troubleshooting

Common issues include missing API tokens, invalid region configuration, connectivity problems, and tools not appearing in Claude. Verify the environment variables, ensure the token is valid, confirm the correct region (Global vs EU), check network access, and restart Claude Desktop after config changes.

API rate limits

Zephyr Scale enforces rate limits. The MCP server automatically retries with exponential backoff and surfaces clear messages when limits are exceeded.

Contributing

Contribute by improving features, fixing bugs, and adding tests where applicable. Follow standard contribution workflows and ensure changes are compatible with MCP tooling.

License

The project is released under the MIT License. Review the LICENSE file for details.

Changelog

v1.0.0 Initial release with complete API coverage, region support, robust error handling, and Claude Desktop integration.

Available tools

health_check

Check API health status of the MCP server and Zephyr Scale integration

get_api_info

Retrieve server configuration info and available endpoints

get_projects

List all Zephyr Scale projects accessible with the provided token

get_project

Get details for a specific Zephyr Scale project by key

get_test_cases

List test cases with filtering options

get_test_case

Get details for a single test case by ID or key

create_test_case

Create a new test case in a specified project

update_test_case

Update an existing test case by ID or key

get_test_case_links

Get all links for a test case

create_test_case_issue_link

Link a test case to a Jira issue

create_test_case_web_link

Create a web link for a test case

get_test_case_versions

Get all versions of a test case

get_test_case_version

Get a specific test case version

get_test_case_script

Get the content of a test script for a test case

create_test_case_script

Create or update a test script for a test case

get_test_case_steps

Get the steps for a test case

create_test_case_steps

Create steps for a test case

get_folders

List folders with filtering options

get_folder

Get details for a specific folder

create_folder

Create a new folder under a project or parent folder

get_test_cycles

List test cycles in a project

get_test_cycle

Get details for a specific test cycle

create_test_cycle

Create a new test cycle in a project

update_test_cycle

Update an existing test cycle

get_test_executions

List test executions in a project or cycle

get_test_execution

Get details for a specific test execution

create_test_execution

Create a new test execution in a project or cycle

update_test_execution

Update execution results for a test execution

get_environments

List environments for a project

get_environment

Get details for a specific environment

create_environment

Create a new environment in a project

update_environment

Update an environment's details