What can you do with this server?

The MCP Zephyr server enables comprehensive test management integration with Zephyr Scale Cloud API through the Model Context Protocol. Core Capabilities: * Project Management: List all Zephyr-integrated Jira projects (up to 1000 results) and retrieve detailed project information by ID or key * Folder Organization: List, retrieve, and create hierarchical folders (TEST_CASE, TEST_PLAN, or TEST_CYCLE types) with filtering by project or parent folder * Test Case Management: List (with project/folder filtering), retrieve, create, and update test cases with full configuration including name, description, priority, status, folder, component, labels, objectives, preconditions, and estimated time * Test Steps Management: Retrieve test steps with pagination (up to 100 per page) or auto-paginate through all steps, and append new steps (max 100 per request) with descriptions, expected results, test data, and attachments * Test Script Management: Retrieve, create, and update BDD/Gherkin or plain text test scripts with Gherkin format validation * Reference Data Access: Retrieve available test case statuses (Draft, Ready, Approved, etc.) and priorities (High, Medium, Low, etc.) individually or in a single consolidated call Key Features: * Pagination support with configurable start positions and max results * JSON schema validation with pattern matching for project keys (\[A-Z]\[A-Z_0-9]+) and test case keys (\[A-Z]+-T\[0-9]+) * Supports US and EU Zephyr regions via environment variables * Integration with VS Code MCP extension, Claude Desktop MCP, and local CLI for debugging Important Constraints: * Test steps and test scripts are mutually exclusive—creating a script removes existing steps * Test steps can only be appended in batches, not individually updated or deleted * Maximum 100 test steps per append request * Pagination limits: typically 1000 max for most endpoints, 100 for test steps

Which integrations are available for this server?

Provides tools for managing test cases, test executions, test cycles, and test plans in Zephyr Scale Cloud, including bulk operations and JQL-based searching for test management within Jira projects.

How do I use MCP Zephyr?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Zephyr create a login test case for the PROJ project" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP Zephyr Server

A comprehensive Model Context Protocol (MCP) server for Zephyr Scale Cloud API that enables seamless integration with your test management workflows.

🚀 Features

Core Capabilities

Project Management: List and retrieve project details
Folder Organization: Create and manage hierarchical folder structures
Test Case Management: Create, read, and update operations for test cases
Test Steps Management: Get and append test steps (note: no individual step update/delete)
Test Script Management: Create and manage BDD/Gherkin test scripts (mutually exclusive with steps)
Reference Data: Access statuses and priorities for test case configuration

🛠️ Available Tools

Project Tools

list_projects - Get all Zephyr-integrated Jira projects
get_project - Retrieve detailed project information

Folder Tools

list_folders - List folders with project/folder filtering
get_folder - Get detailed folder information
create_folder - Create new folders with optional parent hierarchy

Test Case Tools

list_test_cases - List test cases with filtering (project, folder)
get_test_case - Retrieve detailed test case information
create_test_case - Create new test cases with full configuration
update_test_case - Update existing test cases

Test Steps Tools

get_test_steps - Get test steps (paged, 100 items max)
get_all_test_steps - Get all test steps (auto-pagination)
append_test_steps - Add new steps to existing sequence (max 100 per request)

Test Script Tools

get_test_script - Get BDD/Gherkin test script
create_test_script - Create/update test script (removes existing steps)
create_bdd_test_script - Helper for BDD script creation with validation

Reference Data Tools

list_statuses - Get all available statuses (Draft, Ready, Approved, etc.)
list_priorities - Get all available priorities (High, Medium, Low, etc.)
get_reference_data - Get both statuses and priorities in one call

📋 Prerequisites

Node.js 18.0.0 or higher
Zephyr Scale Cloud account with API access
Jira project with Zephyr integration enabled

🔧 Installation

Clone or download this repository
Install dependencies:
npm install
Set up environment variables:
cp .env.example .env
Edit .env and add your Zephyr API token:
ZEPHYR_API_TOKEN=your_bearer_token_here ZEPHYR_REGION=us

🔑 Getting Your API Token

Log in to your Jira Cloud instance
Click on your profile picture in the bottom left
Select "Zephyr API keys"
Generate a new API token
Copy the token to your .env file

🚀 Running the Server

Development Mode

npm run dev

Production Mode

npm start

With MCP Client

# Start the server npm start # In another terminal, use with your MCP client # Configuration will be automatically discovered

🔌 Using This MCP Server

This package is an MCP server that communicates over stdio. It is designed to be launched by an MCP client (for example, the VS Code MCP extension or Claude Desktop). It will appear “idle” if you run it directly, because it waits for MCP protocol messages on stdin.

VS Code MCP Extension

Create or update your MCP config file (for example .vscode/mcp.json) to include this server:

{ "servers": { "zephyr": { "type": "stdio", "command": "mcp-zephyr", "env": { "ZEPHYR_API_TOKEN": "YOUR_TOKEN_HERE", "ZEPHYR_REGION": "us" } } }, "inputs": [] }

Then start the server from the MCP extension UI. It should remain in the Running state and be ready to receive tool calls.

Claude Desktop (MCP)

Add a server entry in your Claude Desktop MCP settings:

{ "mcpServers": { "zephyr": { "command": "mcp-zephyr", "env": { "ZEPHYR_API_TOKEN": "YOUR_TOKEN_HERE", "ZEPHYR_REGION": "us" } } } }

After saving, restart Claude Desktop. The server will be available for tool use in your chats.

Local CLI (for debugging)

If you want to see logs, run with stderr visible:

mcp-zephyr 2> server.log

The server logs are written to stderr to avoid interfering with MCP protocol messages on stdout.

🧰 Testing Individual Tools

For development and debugging, you can test individual tools without running the full MCP server using the test-tools.js script:

List Available Tools

node test-tools.js --list

Test a Tool

# Simple tool without arguments node test-tools.js list_projects # Tool with arguments (pass JSON) node test-tools.js list_projects '{"maxResults": 10}' # Get specific project node test-tools.js get_project '{"projectId": "PROJ1"}' # Create a test case node test-tools.js create_test_case '{"name": "Login Test", "projectKey": "PROJ"}' # List test cases with filtering node test-tools.js list_test_cases '{"projectKey": "PROJ", "maxResults": 5}' # Get reference data node test-tools.js get_reference_data

Note: Make sure your .env file is configured with ZEPHYR_API_TOKEN before running test tools.

📝 Usage Examples

Basic Project Operations

// List all projects { "tool": "list_projects", "arguments": { "maxResults": 50 } } // Get specific project { "tool": "get_project", "arguments": { "projectId": "PROJ" } }

Folder Management

// Create a folder { "tool": "create_folder", "arguments": { "name": "Smoke Tests", "projectKey": "PROJ", "parentFolderId": "123" } }

Test Case Creation

// Create a comprehensive test case { "tool": "create_test_case", "arguments": { "name": "User Login Test", "projectKey": "PROJ", "description": "Verify user can log in with valid credentials", "priorityName": "High", "statusName": "Ready", "folderId": "123", "component": "Authentication", "labels": ["smoke", "regression"], "objective": "Verify login functionality", "precondition": "User exists in system", "estimatedTime": 5 } }

Test Steps Management

// Append test steps { "tool": "append_test_steps", "arguments": { "testCaseKey": "PROJ-T1", "steps": [ { "description": "Navigate to login page", "expectedResult": "Login page is displayed" }, { "description": "Enter valid username and password", "expectedResult": "Credentials are accepted" }, { "description": "Click login button", "expectedResult": "User is logged in and redirected to dashboard" } ] } }

BDD Test Script Creation

// Create BDD script with helper { "tool": "create_bdd_test_script", "arguments": { "testCaseKey": "PROJ-T2", "feature": "User Authentication", "scenario": "Successful login with valid credentials", "steps": [ "Given I am on the login page", "And I have valid user credentials", "When I enter my username and password", "And I click the login button", "Then I should be redirected to the dashboard", "And I should see my username displayed" ] } }

Get Reference Data

// Get all statuses and priorities { "tool": "get_reference_data" }

⚠️ Important Notes

Test Steps vs Test Scripts

Mutually Exclusive: A test case can have either test steps OR a test script, not both
Script Creation Warning: Creating a test script automatically removes existing test steps
Step Limitations: Individual test steps cannot be updated or deleted, only appended in batches

API Constraints

Pagination: Most endpoints support pagination (max 1000 items per request)
Step Limits: Maximum 100 test steps can be added per request
Rate Limits: Respect Zephyr Cloud API rate limits
Region Support: US and EU regions supported via configuration

Data Format

Test Case Keys: Format [A-Z]+-T[0-9]+ (e.g., PROJ-T1)
Project Keys: Format [A-Z][A-Z_0-9]+ (e.g., PROJ, PROJ123)
Folder IDs: Numeric strings (e.g., "123")
Test Scripts: Gherkin format for BDD, plain text for simple scripts

🧪 Testing

# Run tests npm test # Run tests in watch mode npm run test:watch # Run with coverage npm test -- --coverage

🔍 Code Quality

# Run linter npm run lint # Fix linting issues npm run lint:fix

🏗️ Project Structure

mcp-zephyr/ ├── src/ │ ├── config.js # Configuration management │ ├── zephyr-client.js # API client with error handling │ ├── index.js # Main MCP server entry point │ └── tools/ # MCP tool implementations │ ├── project-tools.js │ ├── folder-tools.js │ ├── test-case-tools.js │ ├── test-steps-tools.js │ ├── test-script-tools.js │ └── reference-data-tools.js ├── tests/ # Unit tests │ ├── setup.js │ ├── config.test.js │ ├── zephyr-client.test.js │ └── tools/ │ └── project-tools.test.js ├── .env.example # Environment template ├── package.json # Dependencies and scripts ├── eslint.config.js # ESLint configuration ├── jest.config.js # Jest test configuration └── README.md # This file

🔌 MCP Integration

This server implements the Model Context Protocol specification:

Tool Discovery: Automatic tool listing via ListToolsRequestSchema
Tool Execution: Standardized tool calling via CallToolRequestSchema
Error Handling: Consistent error responses for all operations
JSON Schema: Input validation for all tool parameters

🐛 Troubleshooting

Common Issues

"ZEPHYR_API_TOKEN environment variable is required"
- Ensure you've created .env file with a valid API token
- Check that the token is not expired
"Invalid testCaseKey format"
- Test case keys must match pattern [A-Z]+-T[0-9]+
- Examples: PROJ-T1, PROJECT123-T456
"Request timeout"
- Check your internet connection
- Try reducing maxResults parameter for large requests
"Test case not found"
- Verify the test case key exists in your Zephyr instance
- Ensure you have proper project permissions

Debug Mode

Enable debug logging by setting the environment variable:

DEBUG=* npm start

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run the test suite
Submit a pull request

🆘 Support

Zephyr Documentation: Zephyr Scale Cloud API Docs
MCP Specification: Model Context Protocol
Issues: Report bugs via GitHub Issues

Install Server

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

Resources

Need Help?

Report Issue

Related Servers

Tools

View all tools