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
-
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 -
Install dependencies with UV
uv add fastmcp python-dotenv httpx -
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
-
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
-
Create Environment File Create a
.envfile 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 -
Test Configuration
uv run python zephyr_mcp_server.py
Setup with Claude Desktop
-
Locate Claude Desktop Config
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
-
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" } } } } -
Alternative: Using .env file (Recommended)
{ "mcpServers": { "zephyr-scale": { "command": "uv", "args": ["run", "python", "zephyr_mcp_server.py"], "cwd": "/path/to/your/zephyr-scale-mcp" } } } -
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 filteringget_test_case- Get specific test case detailscreate_test_case- Create new test caseupdate_test_case- Update existing test caseget_test_case_links- Get all links for a test casecreate_test_case_issue_link- Link test case to Jira issuecreate_test_case_web_link- Create web link for test caseget_test_case_versions- Get all versions of test caseget_test_case_version- Get specific versionget_test_case_script- Get test script contentcreate_test_case_script- Create/update test scriptget_test_case_steps- Get test stepscreate_test_case_steps- Create test steps
📁 Folders (3 tools)
get_folders- List folders with filteringget_folder- Get specific folder detailscreate_folder- Create new folder
🔄 Test Cycles (4 tools)
get_test_cycles- List test cyclesget_test_cycle- Get specific test cyclecreate_test_cycle- Create new test cycleupdate_test_cycle- Update existing test cycle
▶️ Test Executions (4 tools)
get_test_executions- List test executionsget_test_execution- Get specific executioncreate_test_execution- Create new executionupdate_test_execution- Update execution results
🏗️ Projects (2 tools)
get_projects- List all projectsget_project- Get specific project details
🔺 Priorities (4 tools)
get_priorities- List prioritiesget_priority- Get specific prioritycreate_priority- Create new priorityupdate_priority- Update existing priority
📊 Statuses (4 tools)
get_statuses- List statusesget_status- Get specific statuscreate_status- Create new statusupdate_status- Update existing status
🌍 Environments (4 tools)
get_environments- List environmentsget_environment- Get specific environmentcreate_environment- Create new environmentupdate_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 issueget_issue_link_test_cycles- Get test cycles linked to Jira issueget_issue_link_test_plans- Get test plans linked to Jira issueget_issue_link_test_executions- Get executions linked to Jira issue
🛠️ Utilities (2 tools)
health_check- Check API healthget_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
-
"API token not set" error
- Ensure
ZEPHYR_API_TOKENis set in.envfile - Verify token is valid and not expired
- Ensure
-
"Connection timeout" errors
- Check network connectivity
- Verify API base URL (Global vs EU region)
-
"Project not found" errors
- Ensure project key exists and is accessible
- Check user permissions in Jira/Zephyr Scale
-
Tools not appearing in Claude
- Verify
claude_desktop_config.jsonsyntax - Check file paths are absolute
- Restart Claude Desktop after config changes
- Verify
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
.envfiles for local development only - Consider using secrets management for production
- Regularly rotate API tokens
- Monitor API usage and access logs
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- 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