Zebrunner MCP Server

A Model Context Protocol (MCP) server that integrates with Zebrunner Test Case Management to help QA teams manage test cases, test suites, and test execution data through AI assistants like Claude.

📖 Need help with installation? Check out our Step-by-Step Install Guide for detailed setup instructions.

🚀 Installing via npm? See our MCP NPM Installation Guide for Claude Desktop, Cursor, IntelliJ IDEA, and ChatGPT Desktop configuration.

📑 Table of Contents

1. 🎯 What is this tool?

2. 🧠 Intelligent Rules System

   • 2.1. What Makes This Tool Special

   • 2.2. How the Rules Work Together

   • 2.3. Why This Matters

   • 2.4. Customizing Rules for Your Project

3. 📋 Prerequisites

4. 🚀 Quick Start Guide

5. 🔧 Usage Methods

   • 5.1. Method 1: Use with Claude Desktop/Code

   • 5.2. Method 2: Run as standalone server

   • 5.3. Method 3: Smart URL-Based Analysis 🚀

6. 🛠️ Available Tools

   • 6.1. 📋 Test Case Management

   • 6.2. 🌳 Test Suite Hierarchy & Organization

   • 6.3. 🔍 Test Coverage & Analysis

   • 6.4. 🧪 Test Code Generation & Validation

   • 6.5. 🚀 Launch & Execution Management

   • 6.6. 📊 Reporting & Analytics

   • 6.7. 🏃 Test Run Management

   • 6.8. 🎯 Management-Focused Quick Commands

7. 🎭 Role-Specific Prompts & Workflows

   • • Daily Test Case Review

     • Test Case Creation & Improvement

     • Test Suite Organization

     • Coverage Analysis

   • • Automation Readiness Assessment

     • Test Code Generation

     • Coverage Analysis & Validation

     • Framework Integration

     • Batch Automation Analysis

   • • Test Case Understanding

     • Implementation Validation

     • Code Generation for Testing

     • Bug Analysis

   • • Team Quality Metrics

     • Test Suite Analysis

     • Team Performance & Planning

     • Process Improvement

     • Reporting & Stakeholder Communication

   • • Project Health Overview

     • Feature Testing Status

     • Quality Assurance Metrics

     • Risk Assessment

     • Planning & Resource Allocation

8. 📖 Output Formats

9. ⚙️ Configuration Options

10. 🧪 Testing Your Setup

11. 🔍 Troubleshooting

12. 🎯 Example Workflows

13. 🔧 Advanced Features

14. 📚 Additional Documentation

15. 🤝 Contributing

16. 📄 License

17. 🎉 You're Ready!

🎯 What is this tool?

This tool allows you to:

• Retrieve test cases and test suites from Zebrunner

• Analyze test coverage and generate test code

• Get test execution results and launch details

• Validate test case quality with automated checks using intelligent rules

• Generate reports and insights from your test data

• Improve test cases with AI-powered suggestions and automated fixes

All through natural language commands in AI assistants!

⬆️ Back to top

🧠 Intelligent Rules System

What Makes This Tool Special

Our MCP server includes a sophisticated 3-tier rules system that transforms how you work with test cases:

🎯 Test Case Review Rules (test_case_review_rules.md)

• Purpose: Core quality standards and writing guidelines

• What it does: Defines fundamental principles for writing high-quality test cases

• Key areas: Independence, single responsibility, comprehensive preconditions, complete step coverage

• Used by: validate_test_case and improve_test_case tools

✅ Test Case Analysis Checkpoints (test_case_analysis_checkpoints.md)

• Purpose: Detailed validation checklist with 100+ checkpoints

• What it does: Provides granular validation criteria for thorough test case analysis

• Key areas: Structure validation, automation readiness, platform considerations, quality assurance

• Used by: validate_test_case for comprehensive scoring and issue detection

⚙️ MCP Zebrunner Rules (mcp-zebrunner-rules.md)

• Purpose: Technical configuration for test generation and coverage analysis

• What it does: Defines framework detection patterns, code templates, and coverage thresholds

• Key areas: Framework detection, test generation templates, coverage thresholds, quality standards

• Used by: generate_draft_test_by_key and get_enhanced_test_coverage_with_rules tools

How the Rules Work Together

Why This Matters

1. Consistency: All team members follow the same quality standards

2. Automation: Reduce manual review time with automated validation

3. Learning: New team members learn best practices through AI feedback

4. Customization: Adapt rules to your project's specific needs

5. Continuous Improvement: AI suggests improvements based on proven patterns

Customizing Rules for Your Project

You can customize any of the three rules files:

Example customizations:

• Mobile projects: Add mobile-specific validation rules

• API projects: Focus on API testing patterns and data validation

• Different frameworks: Customize code generation templates

• Company standards: Align with your organization's testing guidelines

⬆️ Back to top

📋 Prerequisites

What you need to know

• Basic command line usage (opening terminal, running commands)

• Your Zebrunner credentials (login and API token)

• Basic understanding of test management (test cases, test suites)

Software requirements

• Node.js 18 or newer - Download here

• npm (comes with Node.js)

• Access to a Zebrunner instance with API credentials

How to check if you have Node.js

Open your terminal/command prompt and run:

If you see version numbers, you're ready to go!

⬆️ Back to top

🚀 Quick Start Guide

💡 Want more detailed instructions? Check out our More Detailed Step-by-step Install Guide with troubleshooting tips and platform-specific instructions.

Step 1: Get the code

Choose one of these methods:

Option A: Clone from repository (recommended)

Option B: Download and extract

Download the project files and extract them to a folder.

Step 2: Install dependencies

Step 3: Configure your Zebrunner connection

Create a .env file in the project folder with your Zebrunner details:

How to get your Zebrunner API token:

1. Log into your Zebrunner instance

2. Go to your profile settings

3. Find the "API Access" section

4. Generate a new API token

5. Copy the token to your .env file

Step 4: Build the project

Step 5: Test your connection

If you see "✅ Health check completed", you're ready to go!

🔄 Updating to New Version

Check current version

Update steps

Important Notes:

• ✅ Your for the health check to work

• ✅ Restart Claude Desktop/Code after updating to reload the MCP server

• ✅ Check release notes for any breaking changes before updating

If the health check fails, verify your .env configuration and Zebrunner credentials.

⬆️ Back to top

🔧 Usage Methods

Method 1: Use with Claude Desktop/Code (Recommended)

Add this configuration to your Claude Desktop or Claude Code settings. Important: You must use the full absolute path to your project folder.

Example paths:

• Windows: C:\\Users\\YourName\\Projects\\mcp-zebrunner\\dist\\server.js

• macOS/Linux: /Users/YourName/Projects/mcp-zebrunner/dist/server.js

Alternative: Command Line Integration (Claude Code)

You can also add the server using the command line:

Important: Replace /full/absolute/path/to/mcp-zebrunner/ with the actual full path to your project folder.

Method 2: Run as standalone server

Development mode (with auto-reload)

Production mode

Method 3: Smart URL-Based Analysis 🚀

NEW in v5.4.1+: Claude can automatically detect Zebrunner URLs and analyze them with optimal settings!

Just paste a Zebrunner URL in your conversation, and Claude will automatically:

• Parse the URL to extract project, launch, and test IDs

• Call the appropriate analysis tool

• Use recommended settings (videos, screenshots, AI analysis enabled)

📋 Supported URL Patterns

1. Test Analysis URLs

What happens:

• Claude automatically calls analyze_test_failure

• Extracts: projectKey, testRunId (launch ID), testId

• Enables: includeVideo: true, analyzeScreenshotsWithAI: true, all diagnostics

Example:

2. Launch Analysis URLs

What happens:

• Claude automatically calls detailed_analyze_launch_failures

• Extracts: projectKey, testRunId (launch ID)

• Enables: includeScreenshotAnalysis: true, comprehensive analysis

Example:

✨ Advanced Usage

Override Default Settings

Claude understands natural language overrides:

Multiple URLs

Analyze multiple tests/launches in one request:

Cross-Workspace Support

⚠️ URLs from different workspaces will show a warning but still attempt analysis:

📖 URL Pattern Reference

🎯 Why Use URL-Based Analysis?

✅ Faster: No need to manually specify IDs
✅ Convenient: Copy-paste URLs directly from Zebrunner UI
✅ Optimized: Automatic use of recommended settings
✅ Smart: Claude detects intent and adjusts parameters
✅ Flexible: Natural language overrides work seamlessly

💡 Pro Tips

1. Direct from Zebrunner: Copy URL directly from your browser while viewing a test/launch

2. Batch Analysis: Paste multiple URLs separated by newlines

3. Custom Settings: Add natural language instructions to override defaults

4. Quick Checks: URLs work great for quick "what happened here?" questions

5. Reports: Combine with format requests: "Generate JIRA ticket for https://...url..."

⬆️ Back to top

🛠️ Available Tools

Once connected, you can use these tools through natural language in your AI assistant. Here's a comprehensive reference of all 33+ available tools organized by category:

📋 Test Case Management

Core Test Case Tools

Batch Test Case Operations

🌳 Test Suite Hierarchy & Organization

Suite Management

Suite Analysis Tools

🔍 Test Coverage & Analysis

Coverage Analysis

Duplicate Analysis

🔗 Clickable Links Feature: Both duplicate analysis tools support clickable links to Zebrunner web UI:

• Add include_clickable_links: true to make test case keys clickable in markdown output

• JSON/DTO formats automatically include webUrl fields when enabled

• Links are generated from your ZEBRUNNER_URL environment variable

• Example: "Analyze suite 17585 for duplicates with clickable links enabled"

🧪 Test Code Generation & Validation

AI-Powered Tools

🚀 Launch & Execution Management

Launch Operations ⭐ Essential for Managers

📊 Reporting & Analytics

Test Failure Analysis 🆕 Game Changer

✅ FIXED in v5.2.4! Improved Reliability & Video Links

• 🎥 Video URLs fixed: Now uses test-sessions API (/api/reporting/v1/launches/{id}/test-sessions) for reliable video artifact extraction

• 🛡️ Comprehensive error handling: Gracefully handles missing screenshots/logs (returns empty arrays instead of throwing)

• 🚫 No more "no result received" errors: All API calls have proper try-catch blocks with fallbacks

• 🐛 Better debugging: Enhanced logging when debug: true is enabled in config

• 📊 Schema updates: Supports both old and new API structures for backward compatibility

🎫 NEW in v4.12.1! Jira-Ready Ticket Format

• Use format: 'jira' to generate ready-to-paste Jira tickets

• Auto-calculated priority based on stability and impact

• Smart labels: test-automation, locator-issue, flaky-test, etc.

• Complete Jira markup: Tables, panels, code blocks, clickable links

• 🎥 Prominent video links: Beautiful panels + links section

• Copy-paste ready: No manual formatting needed

• Saves 5-10 minutes per ticket with consistent quality

🧠 Enhanced in v4.11.1! detailed_analyze_launch_failures provides automatic deep synthesis like Claude would manually provide:

• 🎯 Executive Summary: Key findings, patterns, and stability indicators

• 📅 Timeline Analysis: When failures first appeared, progression tracking

• 🔬 Pattern Analysis: Groups by root cause with affected tests and stability %

• 🎯 Priority-Based Recommendations: 🔴 HIGH / 🟡 MEDIUM / 🟢 LOW with impact analysis

• 📋 Enhanced Test Details: Full error messages, stack traces, timestamps

• ❓ Smart Follow-up Questions: Guides next investigation steps

• Smart filtering: Analyzes only tests WITHOUT linked issues by default

• Optional AI screenshot analysis for all tests

• No manual follow-up needed - get complete picture in one call!

🆕 NEW in v5.11.0! Test Execution History & Comparison

• 📊 Track execution trends: View pass/fail history across launches with get_test_execution_history

• 🔄 Compare with last passed: New compareWithLastPassed parameter in analyze_test_failure

  • Compare logs (new errors detection)

  • Compare duration (performance regression)

  • Compare environment (device/platform changes)

  • Compare screenshots (visual differences)

• ⚠️ Critical detection: Automatically highlights when test failed in all recent executions

• 🎯 Regression analysis: See exactly what changed between passed and failed runs

• 📈 Pass rate metrics: Calculate test stability over time

• See TOOLS_CATALOG.md for example prompts!

Screenshot Analysis & Visual Forensics 🎯 Enhanced in v4.11.0

📸 Enhanced! Screenshot analysis now integrated directly into analyze_test_failure and analyze_launch_failures - no need to call separately! See Screenshot Analysis Guide for details.

Platform & Results Analysis ⭐ Critical for Management

Project Discovery

🏃 Test Run Management

Public API Test Runs ⭐ Powerful for Analysis

Configuration Management

🎯 Management-Focused Quick Commands

📈 Daily Standup Reports

🔍 Test Suite Optimization

📊 Weekly Management Reports

🎯 Milestone & Release Planning

🐞 Issue Analysis & Troubleshooting

⬆️ Back to top

🎭 Role-Specific Prompts & Workflows

👩‍💻 Manual QA Engineers

Daily Test Case Review

Test Case Creation & Improvement

Test Suite Organization

Coverage Analysis

🤖 Test Automation Engineers & SDETs

Automation Readiness Assessment

Test Code Generation

Coverage Analysis & Validation

Framework Integration

Batch Automation Analysis

👨‍💻 Developers

Test Case Understanding

Implementation Validation

Code Generation for Testing

Bug Analysis

👔 Test Managers & Team Leads

Team Quality Metrics

Test Suite Analysis

Team Performance & Planning

Process Improvement

Reporting & Stakeholder Communication

Daily Management Tasks

🏢 Project Owners & Product Managers

Project Health Overview

Feature Testing Status

Quality Assurance Metrics

Risk Assessment

Planning & Resource Allocation

Executive Reporting

⬆️ Back to top

📖 Output Formats

All tools support multiple output formats:

• json - Structured data (default)

• markdown - Rich formatted output with sections and tables

• string - Human-readable text summaries

• dto - Raw data objects

Example:

⬆️ Back to top

⚙️ Configuration Options

Environment Variables

Rules System Configuration

The rules system automatically detects and uses rules files in your project root:

Automatic Detection

If you have a mcp-zebrunner-rules.md file in your project root, the rules engine will automatically enable itself.

Custom Rules Files

You can customize the three types of rules:

1. Test Case Review Rules (test_case_review_rules.md)

2. Analysis Checkpoints (test_case_analysis_checkpoints.md)

3. Technical Rules (mcp-zebrunner-rules.md)

⬆️ Back to top

🧪 Testing Your Setup

Run health checks

Test API connection

Run full test suite

Run specific test types

⬆️ Back to top

🔍 Troubleshooting

Common Issues

"Authentication failed" or 401 errors

• ✅ Check your ZEBRUNNER_LOGIN and ZEBRUNNER_TOKEN

• ✅ Verify your API token is still valid

• ✅ Ensure your user has proper permissions in Zebrunner

"Project not found" or 404 errors

• ✅ Check the project key spelling (e.g., "MYAPP", not "myapp")

• ✅ Verify you have access to the project in Zebrunner

• ✅ Some endpoints may not be available on all Zebrunner instances

"Connection timeout" errors

• ✅ Check your ZEBRUNNER_URL is correct

• ✅ Ensure your network can reach the Zebrunner instance

• ✅ Try increasing timeout in configuration

MCP integration not working

• ✅ Verify the path to dist/server.js is correct

• ✅ Check that the project built successfully (npm run build)

• ✅ Ensure environment variables are set in MCP configuration

• ✅ Look at Claude Desktop/Code logs for error messages

Rules engine not working

• ✅ Check that ENABLE_RULES_ENGINE=true in your .env file

• ✅ Verify rules files exist and have meaningful content

• ✅ Restart the MCP server after changing rules files

• ✅ Check debug logs for rules parsing errors

Debug Mode

Enable detailed logging to troubleshoot issues:

This will show:

• API requests and responses

• Error details and stack traces

• Performance metrics

• Feature availability

• Rules parsing and validation details

Getting Help

1. Check the logs - Enable debug mode and look for error messages

2. Test your connection - Run npm run test:health

3. Verify your configuration - Double-check your .env file

4. Check Zebrunner permissions - Ensure your user has proper access

5. Validate rules files - Ensure rules files have meaningful content

⬆️ Back to top

🎯 Example Workflows

Workflow 1: Test Case Review (Manual QA)

Workflow 2: Test Automation (SDET)

Workflow 3: Implementation Validation (Developer)

Workflow 4: Quality Management (Team Lead)

Workflow 5: Project Health (Product Manager)

⬆️ Back to top

🔧 Advanced Features

Batch Operations

Process multiple test cases at once:

Custom Output Formats

Get data in the format you need:

Filtering and Search

Find exactly what you need:

Rules-Based Analysis

Leverage intelligent validation:

📚 Additional Documentation

📖 Tool References

• TOOLS_CATALOG.md - 🆕 Complete catalog of all 40+ tools with natural language examples

• INSTALL-GUIDE.md - 📥 Step-by-step installation and setup guide

🧠 Intelligent Rules System

• docs/INTELLIGENT_RULES_SYSTEM.md - 🧠 Complete guide to the 3-tier intelligent rules system

• docs/RULES_QUICK_REFERENCE.md - ⚡ Quick reference for rules system commands and configuration

📋 Rules Files (Customizable)

• test_case_review_rules.md - 🎯 Core quality standards and writing guidelines

• test_case_analysis_checkpoints.md - ✅ 100+ detailed validation checkpoints

• mcp-zebrunner-rules.md - ⚙️ Technical configuration for test generation and coverage analysis

🔍 Specialized Guides

• docs/SCREENSHOT_ANALYSIS.md - 📸 Screenshot download and visual analysis guide

• change-logs.md - 📝 Version history and feature updates

🛠️ Feature Documentation

• docs/NEW_LAUNCHER_TOOL.md - Detailed information about launch and reporting tools

• docs/SUITE_HIERARCHY.md - Complete guide to suite hierarchy features

• docs/TEST_CASE_VALIDATION_IMPLEMENTATION.md - Test case validation system details

• docs/ENHANCED_VALIDATION_FEATURES.md - Advanced validation and improvement features

• docs/SCREENSHOT_ANALYSIS.md - 📸 Screenshot analysis and visual forensics guide 🆕

⬆️ Back to top

🤝 Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes with appropriate tests

4. Ensure all tests pass: npm test

5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🎉 You're Ready!

Once you've completed the setup:

1. Test your connection with npm run test:health

2. Configure your AI assistant with the MCP server

3. Start asking questions about your test cases!

Example first commands to try:

• "List test suites for project [YOUR_PROJECT_KEY]"

• "Get test case [YOUR_TEST_CASE_KEY] details"

• "Validate test case [YOUR_TEST_CASE_KEY]"

• "Show me the test suite hierarchy"

The intelligent rules system will help ensure your test cases meet quality standards and are ready for both manual execution and automation. Happy testing! 🚀