Zephyr Scale MCP Server

A Model Context Protocol (MCP) server for Zephyr Scale Test Management. This server provides comprehensive tools for interacting with Zephyr Scale through any LLM that supports MCP.

Features

• Test Case Management: Search, view, and manage test cases

• Test Run Operations: Create, clone, and manage test runs

• Folder Management: Organize test runs in folders with automated workflows

• Assignment Tools: Bulk assign test results to team members

• Complete Workflows: Automated folder creation and test run cloning

Related MCP server: Zephyr Scale MCP Server

Prerequisites

• Python 3.10+

• Jira instance with Zephyr Scale installed

• Jira API token (generate from your Atlassian account settings)

Installation

# Clone the repository
git clone https://github.com/ivinitus/zephyr-scale-mcp.git
cd zephyr-scale-mcp

# Install the package
pip install -e .

# Or install dependencies manually
pip install -r requirements.txt

Configuration

Set the following environment variables:

export ZEPHYR_BASE_URL="https://your-domain.atlassian.net"
export ZEPHYR_USERNAME="your-email@example.com"
export ZEPHYR_API_TOKEN="your-api-token"

Getting Your API Token

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens

2. Click "Create API token"

3. Give it a label and copy the token

4. Use your email as username and the token as password

Usage with MCP Clients

Amazon Q Developer

Add to your MCP configuration:

{
  "mcpServers": {
    "zephyr-scale": {
      "command": "python",
      "args": ["-m", "zephyr_scale_mcp"],
      "env": {
        "ZEPHYR_BASE_URL": "https://your-domain.atlassian.net",
        "ZEPHYR_USERNAME": "your-email@example.com",
        "ZEPHYR_API_TOKEN": "your-api-token"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "zephyr-scale": {
      "command": "python",
      "args": ["-m", "zephyr_scale_mcp"],
      "env": {
        "ZEPHYR_BASE_URL": "https://your-domain.atlassian.net",
        "ZEPHYR_USERNAME": "your-email@example.com",
        "ZEPHYR_API_TOKEN": "your-api-token"
      }
    }
  }
}

Available Tools

Test Case Tools

• get_testcase_detail - Get detailed information about a test case

• search_testcases - Search for test cases with filters

• get_testcase_attachments - Get attachments for a test case

• get_testcase_latest_result - Get the latest test result

Test Run Tools

• get_testrun_details - Get test run information

• get_testrun_results - Get all results for a test run

• search_testruns - Search for test runs

• get_testrun_items - Get test run items with details

Assignment Tools

• update_test_assignee - Assign a test result to a user

• bulk_update_test_assignees - Bulk assign multiple test results

Folder Management Tools

• get_folder_tree - Get folder structure

• find_folder_by_name - Find a folder by name

• get_test_runs_in_folder - Get all test runs in a folder

• create_test_folder - Create a new folder

• generate_folder_name - Generate folder name with date

• check_folder_exists - Check if folder exists

Test Run Management Tools

• bulk_clone_test_runs - Clone multiple test runs

• bulk_move_test_runs - Move test runs to a folder

• bulk_rename_test_runs - Rename test runs (remove cloned suffix)

• get_recently_created_test_runs - Get recently created test runs

Workflow Tools

• create_folder_and_clone_runs - Complete workflow to create folder and clone test runs

Example Prompts

Once configured, you can ask your LLM:

• "Show me test case PROJECT-T123"

• "Search for test cases in project ABC with status 'Draft'"

• "Create a new folder called 'Sprint 24 Testing' in project 12345"

• "Clone all test runs from folder 'Sprint 23' to a new folder 'Sprint 24'"

• "Assign test results 123, 456, 789 to John Doe"

Project Structure

zephyr-scale-mcp/
├── client.py          # Zephyr Scale API client
├── server.py          # MCP server with tool definitions
├── __init__.py        # Package initialization
├── README.md          # This file
├── requirements.txt   # Python dependencies
└── .env.example       # Example environment variables

Development

Running Tests

python -m pytest tests/

Adding New Tools

1. Add the method to ZephyrClient in client.py

2. Create a tool function in server.py with the @handle_api_errors decorator

3. Register the tool in the register_tools() function

4. Export it in __init__.py

Security Notes

• Never commit your API token to version control

• Use environment variables or secure secret management

• API tokens have the same permissions as your user account

• Consider creating a dedicated service account for automation

Troubleshooting

Authentication Errors

• Verify your API token is correct and not expired

• Check that your username is your email address

• Ensure your user has access to the Jira project

Connection Errors

• Verify the base URL is correct (no trailing slash)

• Check your network connection and firewall settings

• Ensure Zephyr Scale is installed on your Jira instance

Tool Errors

• Check that project IDs are numeric strings

• Verify test case/run keys follow the format "PROJECT-T123"

• Ensure you have permissions for the operations you're attempting

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT License - feel free to use this in your projects!

Acknowledgments

Built for the MCP ecosystem to enable AI-powered test management workflows.