jira-zephyr-mcp

JIRA Zephyr MCP Server

A Model Context Protocol (MCP) server that provides comprehensive integration with JIRA's Zephyr test management system. This server enables seamless test management operations including creating test plans, managing test cycles, executing tests, and reading JIRA issues.

Features

Core Capabilities

• Test Plan Management: Create and list test plans in Zephyr
• Test Cycle Management: Create and manage test execution cycles
• JIRA Integration: Read JIRA issue details and metadata
• Test Execution: Update test execution results and status
• Progress Tracking: Monitor test execution progress and statistics
• Issue Linking: Associate test cases with JIRA issues
• Reporting: Generate comprehensive test execution reports

Available Tools

1. read_jira_issue - Retrieve JIRA issue information
2. create_test_plan - Create new test plans in Zephyr
3. list_test_plans - Browse existing test plans
4. create_test_cycle - Create test execution cycles
5. list_test_cycles - View test cycles with execution status
6. execute_test - Update test execution results
7. get_test_execution_status - Check test execution progress
8. link_tests_to_issues - Associate tests with JIRA issues
9. generate_test_report - Create test execution reports

Prerequisites

• Node.js 18.0.0 or higher
• JIRA instance with Zephyr Scale or Zephyr Squad
• Valid JIRA API credentials
• Zephyr API access token

Integration with Cursor

Clone the project, then add the following to your Cursor configuration:

{
  "mcpServers": {
    "jira-zephyr": {
      "command": "node",
      "args": ["/path/to/jira-zephyr-mcp/dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your-email@company.com",
        "JIRA_API_TOKEN": "your-jira-api-token",
        "ZEPHYR_API_TOKEN": "your-zephyr-api-token"
      }
    }
  }
}

Using Docker

Alternatively, you can configure Cursor to run the MCP server in Docker (ensure the image is built first):

{
  "mcpServers": {
    "jira-zephyr": {
      "command": "docker",
      "args": ["run", "--rm", "-i","-e","JIRA_BASE_URL","-e","JIRA_USERNAME","-e","JIRA_API_TOKEN","-e","ZEPHYR_API_TOKEN", "jira-zephyr-mcp"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your-email@company.com",
        "JIRA_API_TOKEN": "your-jira-api-token",
        "ZEPHYR_API_TOKEN": "your-zephyr-api-token"
      }
    }
  }
}

Installation (for development)

1. Clone the repository:

git clone https://github.com/your-username/jira-zephyr-mcp.git
cd jira-zephyr-mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

1. Copy the example environment file:

cp .env.example .env

2. Configure your JIRA and Zephyr credentials in .env:

JIRA_BASE_URL=https://your-domain.atlassian.net
JIRA_USERNAME=your-email@company.com
JIRA_API_TOKEN=your-jira-api-token
ZEPHYR_API_TOKEN=your-zephyr-api-token

Getting API Tokens

JIRA API Token

1. Go to Atlassian Account Settings
2. Navigate to Security → API tokens
3. Create a new API token
4. Copy the token to your .env file

Zephyr API Token

1. In JIRA, go to Apps → Zephyr Scale → API Access Tokens
2. Generate a new token
3. Copy the token to your .env file

Usage

Development

npm run dev

Production

npm start

Running with Docker

You can containerize and run the MCP server using Docker.

Prerequisites

• Docker installed on your system
• The project cloned locally

Building the Docker Image

1. Navigate to the project directory:

cd /path/to/jira-zephyr-mcp

2. Build the Docker image:

docker build -t jira-zephyr-mcp:latest .

You can specify a different tag if desired, e.g., -t jira-zephyr-mcp:v1.0.0.

Running the Container

1. Run the container with required environment variables:

docker run -d --name jira-zephyr-mcp \
  -e JIRA_BASE_URL=https://your-domain.atlassian.net \
  -e JIRA_USERNAME=your-email@company.com \
  -e JIRA_API_TOKEN=your-jira-api-token \
  -e ZEPHYR_API_TOKEN=your-zephyr-api-token \
  jira-zephyr-mcp:latest

Note: For integration with systems like Cursor, use the Docker configuration shown in the 'Integration with Cursor' section above. Ensure the image is built with the desired tag that matches your Cursor config. The server communicates via stdio, so ensure your setup supports this when running in a container.

Tool Usage Examples

Reading JIRA Issues

// Read basic issue information
await readJiraIssue({ issueKey: "ABC-123" });

// Read specific fields
await readJiraIssue({ 
  issueKey: "ABC-123", 
  fields: ["summary", "status", "assignee"] 
});

Creating Test Plans

await createTestPlan({
  name: "Release 2.0 Test Plan",
  description: "Comprehensive testing for release 2.0",
  projectKey: "ABC",
  startDate: "2024-01-15",
  endDate: "2024-01-30"
});

Managing Test Cycles

// Create a test cycle
await createTestCycle({
  name: "Sprint 10 Testing",
  description: "Testing for sprint 10 features",
  projectKey: "ABC",
  versionId: "10001",
  environment: "Production"
});

// List test cycles
await listTestCycles({
  projectKey: "ABC",
  limit: 25
});

Test Execution

// Update test execution status
await executeTest({
  executionId: "12345",
  status: "PASS",
  comment: "All tests passed successfully"
});

// Get execution status
await getTestExecutionStatus({ cycleId: "67890" });

Generating Reports

// Generate JSON report
await generateTestReport({
  cycleId: "67890",
  format: "JSON"
});

// Generate HTML report
await generateTestReport({
  cycleId: "67890",
  format: "HTML"
});

Error Handling

The server implements comprehensive error handling:

• Input validation using Zod schemas
• API error mapping and user-friendly messages
• Network timeout handling
• Authentication error detection

Development

Scripts

• npm run build - Build the TypeScript project
• npm run dev - Run in development mode with file watching
• npm run lint - Run ESLint
• npm run typecheck - Run TypeScript type checking

Project Structure

src/
├── index.ts              # Main MCP server entry point
├── clients/              # API clients
│   ├── jira-client.ts    # JIRA REST API client
│   └── zephyr-client.ts  # Zephyr API client
├── tools/                # MCP tool implementations
│   ├── jira-issues.ts    # JIRA issue tools
│   ├── test-plans.ts     # Test plan management
│   ├── test-cycles.ts    # Test cycle management
│   └── test-execution.ts # Test execution tools
├── types/                # TypeScript type definitions
│   ├── jira-types.ts     # JIRA API types
│   └── zephyr-types.ts   # Zephyr API types
└── utils/                # Utility functions
    ├── config.ts         # Configuration management
    └── validation.ts     # Input validation schemas

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

Security

• Never commit API tokens or credentials to the repository
• Use environment variables for all sensitive configuration
• Regularly rotate API tokens
• Implement proper access controls in your JIRA instance

License

MIT License - see LICENSE file for details

Support

For issues and questions:

1. Check the existing GitHub issues
2. Create a new issue with detailed information
3. Include error logs and configuration (without sensitive data)

Roadmap

• Support for Zephyr Squad (in addition to Zephyr Scale)
• Bulk test execution operations
• Advanced reporting with charts and metrics
• Test case creation and management
• Integration with CI/CD pipelines
• Custom field support for test management