Zephyr Scale MCP Server

A comprehensive Model Context Protocol (MCP) server for SmartBear Zephyr Scale test management platform. This server provides seamless integration with Zephyr Scale's REST API, enabling automated test management workflows through Claude and other MCP-compatible tools.

Table of Contents

• Features
• Code Structure
• Prerequisites
• Installation
• Configuration
• Setup with Claude Desktop
• Available Tools
• Usage Examples
• Error Handling
• Contributing
• License

Features

• Complete API Coverage: All major Zephyr Scale endpoints
• Region Support: Global and EU region APIs
• Comprehensive Error Handling: Detailed error messages and status codes
• Type Safety: Proper type hints and enums
• Pagination Support: Handle large datasets efficiently
• Flexible Authentication: JWT token-based authentication
• Logging: Comprehensive logging for debugging

Code Structure

zephyr-scale-mcp/
├── .venv/                    # UV virtual environment
├── zephyr_mcp_server.py      # Main MCP server implementation
├── .env                      # Environment variables (create this)
├── pyproject.toml           # UV project configuration
├── uv.lock                  # UV lock file
├── .gitignore               # Git ignore file
└── README.md                # This file

Core Components

# Main server initialization
mcp = FastMCP("zephyr-scale")

# HTTP client with error handling
async def make_zephyr_request(method, url, data=None, params=None)

# Tool categories:
# - Test Cases (13 tools)
# - Folders (3 tools) 
# - Test Cycles (4 tools)
# - Test Executions (4 tools)
# - Projects (2 tools)
# - Priorities (4 tools)
# - Statuses (4 tools)
# - Environments (4 tools)
# - Links (1 tool)
# - Issue Links (4 tools)
# - Utilities (2 tools)

Prerequisites

• Python 3.8+
• Zephyr Scale account with API access
• Jira instance connected to Zephyr Scale
• Valid Zephyr Scale API token

Installation

1. Initialize UV project

   # Create project directory
   mkdir zephyr-scale-mcp
   cd zephyr-scale-mcp
   
   # Initialize uv project
   uv init
   
   # Save the zephyr_mcp_server.py file in this directory
   

2. Install dependencies with UV

   uv add fastmcp python-dotenv httpx
   

3. Your pyproject.toml should look like

   [project]
   name = "zephyr-scale-mcp"
   version = "0.1.0"
   description = "Zephyr Scale MCP Server"
   dependencies = [
       "fastmcp>=0.1.0",
       "dotenv>=1.0.0",
       "httpx>=0.25.0",
   ]
   requires-python = ">=3.8"
   

Configuration

1. Generate Zephyr Scale API Token

   • Log into your Jira instance
   • Click on your profile picture (bottom left)
   • Select "Zephyr API keys"
   • Generate a new API key
   • Copy the token for configuration

2. Create Environment File Create a .env file in the project directory:

   # 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
   

3. Test Configuration

   uv run python zephyr_mcp_server.py
   

Setup with Claude Desktop

1. Locate Claude Desktop Config

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add MCP Server Configuration

   {
     "mcpServers": {
       "zephyr-scale": {
         "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"
         }
       }
     }
   }
   

3. Alternative: Using .env file (Recommended)

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

4. Restart Claude Desktop

   • Close Claude Desktop completely
   • Restart the application
   • The Zephyr Scale tools should now be available

Available Tools

📝 Test Cases (13 tools)

• get_test_cases - List test cases with filtering
• get_test_case - Get specific test case details
• create_test_case - Create new test case
• update_test_case - Update existing test case
• get_test_case_links - Get all links for a test case
• create_test_case_issue_link - Link test case to Jira issue
• create_test_case_web_link - Create web link for test case
• get_test_case_versions - Get all versions of test case
• get_test_case_version - Get specific version
• get_test_case_script - Get test script content
• create_test_case_script - Create/update test script
• get_test_case_steps - Get test steps
• create_test_case_steps - Create test steps

📁 Folders (3 tools)

• get_folders - List folders with filtering
• get_folder - Get specific folder details
• create_folder - Create new folder

🔄 Test Cycles (4 tools)

• get_test_cycles - List test cycles
• get_test_cycle - Get specific test cycle
• create_test_cycle - Create new test cycle
• update_test_cycle - Update existing test cycle

▶️ Test Executions (4 tools)

• get_test_executions - List test executions
• get_test_execution - Get specific execution
• create_test_execution - Create new execution
• update_test_execution - Update execution results

🏗️ Projects (2 tools)

• get_projects - List all projects
• get_project - Get specific project details

🔺 Priorities (4 tools)

• get_priorities - List priorities
• get_priority - Get specific priority
• create_priority - Create new priority
• update_priority - Update existing priority

📊 Statuses (4 tools)

• get_statuses - List statuses
• get_status - Get specific status
• create_status - Create new status
• update_status - Update existing status

🌍 Environments (4 tools)

• get_environments - List environments
• get_environment - Get specific environment
• create_environment - Create new environment
• update_environment - Update existing environment

🔗 Links (1 tool)

• delete_link - Delete any link by ID

🎯 Issue Links (4 tools)

• get_issue_link_test_cases - Get test cases linked to Jira issue
• get_issue_link_test_cycles - Get test cycles linked to Jira issue
• get_issue_link_test_plans - Get test plans linked to Jira issue
• get_issue_link_test_executions - Get executions linked to Jira issue

🛠️ Utilities (2 tools)

• health_check - Check API health
• get_api_info - Get server configuration info

Usage Examples

1. Create a Test Case

Create a test case named "User Login Validation" for project "DEMO" with high priority and objective "Validate user authentication flow"

2. Organize Tests with Folders

Create a folder structure for organizing regression tests in project "DEMO"

3. Execute Test Cycles

Create a test cycle for Sprint 1 testing in project "DEMO" and show me all test executions

4. Link Tests to Issues

Link test case DEMO-T123 to Jira issue DEMO-456

5. Manage Test Environments

Create testing environments for Chrome, Firefox, and Safari browsers in project "DEMO"

6. Generate Test Reports

Get all test executions for project "DEMO" from the last 7 days and summarize the results

7. Bulk Operations

Get all test cases in folder ID 100 and update their priority to "High"

8. Integration Workflows

For each failed test execution, create a Jira issue and link it to the test case

Error Handling

The server includes comprehensive error handling:

• HTTP Errors: Detailed status codes and messages
• Authentication Errors: Clear token validation feedback
• Validation Errors: Parameter validation with helpful messages
• Network Errors: Timeout and connection error handling
• JSON Parsing: Graceful handling of malformed responses

Example error response:

{
  "error": "HTTP 401: Unauthorized - Invalid API token",
  "status_code": 401
}

Troubleshooting

Common Issues

1. "API token not set" error

   • Ensure ZEPHYR_API_TOKEN is set in .env file
   • Verify token is valid and not expired

2. "Connection timeout" errors

   • Check network connectivity
   • Verify API base URL (Global vs EU region)

3. "Project not found" errors

   • Ensure project key exists and is accessible
   • Check user permissions in Jira/Zephyr Scale

4. Tools not appearing in Claude

   • Verify claude_desktop_config.json syntax
   • Check file paths are absolute
   • Restart Claude Desktop after config changes

Debug Mode

Enable debug logging by modifying the server:

logging.basicConfig(level=logging.DEBUG)

API Rate Limits

Zephyr Scale has rate limits. The server handles these gracefully:

• Automatic retry for rate limit errors
• Exponential backoff strategy
• Clear error messages when limits are exceeded

Security Considerations

• Store API tokens securely in environment variables
• Use .env files for local development only
• Consider using secrets management for production
• Regularly rotate API tokens
• Monitor API usage and access logs

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

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues related to:

• This MCP Server: Create an issue in this repository
• Zephyr Scale API: Contact SmartBear support
• Claude Desktop: Contact Anthropic support

Changelog

v1.0.0

• Initial release with complete API coverage
• Support for all major Zephyr Scale endpoints
• Comprehensive error handling
• Region support (Global/EU)
• Claude Desktop integration