MCP Jira Xray Server

A Model Context Protocol (MCP) server for extracting test information from Jira Xray. This server connects to Jira instances with Xray Test Management and extracts test cases related to specific tickets.

Features

• 🔍 Extract tests related to any Jira ticket
• 📋 List test executions linked to tickets
• 🎨 Configurable JSON output format
• 💾 Automatic saving to the extractions folder
• 🔐 Secure connection using Jira API tokens

Installation

Prerequisites

• Node.js 17 or higher
• A Jira instance with Xray Test Management
• Jira API token

Setup

1. Clone this repository or install via npm:

git clone <repository-url>
cd mcp-jira-xray
npm install

2. Run the interactive setup:

npm run setup

This will guide you through:

• Entering your Jira host URL
• Providing your Jira email
• Adding your API token
• Validating the connection
• Configuring output format

Or manually create a .env file:

cp .env.example .env
# Edit .env with your credentials

Getting a Jira API Token

1. Go to Atlassian Account Settings
2. Click "Create API token"
3. Give it a label and copy the token
4. Use this token in your .env file

Configuration

Jira Connection

The server requires three configuration values:

• JIRA_HOST: Your Jira instance URL (e.g., https://mycompany.atlassian.net)
• JIRA_EMAIL: Your Jira account email
• JIRA_API_TOKEN: Your Jira API token

Output Format

The OUTPUT_FORMAT environment variable defines the JSON structure for extracted test data. You can customize this to match your needs.

Default format:

{
  "ticketId": "",
  "test": "",
  "testCases": []
}

Custom format example:

{
  "ticket": {
    "id": "",
    "name": ""
  },
  "tests": {
    "cases": []
  }
}

The server will populate the fields based on these keys:

• ticketId → The Jira ticket ID
• test → The ticket summary
• testCases → Array of test case descriptions

Usage

With VS Code

Good news! The server is already configured for this project in .vscode/mcp.json.

Quick Start:

1. Make sure you've run npm run setup (configuration complete)
2. Open Command Palette: Cmd/Ctrl + Shift + P
3. Type: "MCP: Enable" and press Enter
4. Try: "Extract tests for ticket PROJ-123" in Copilot Chat

📖 See VSCODE-SETUP.md for complete VS Code installation guide

With Claude Desktop

Add this to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "jira-xray": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-jira-xray/build/index.js"]
    }
  }
}

Available Tools

1. extract_tests

Extracts all tests related to a given Jira ticket.

Parameters:

• ticketId (string): The Jira ticket ID (e.g., "PROJ-123")

Example:

Extract tests for ticket PROJ-123

Output:

• Test execution details
• All test cases with descriptions
• Saved to extractions/PROJ-123_<timestamp>.json

2. list_test_executions

Lists all test executions linked to a Jira ticket.

Parameters:

• ticketId (string): The Jira ticket ID

Example:

List test executions for PROJ-123

Output:

• List of test execution keys
• Test execution summaries
• Execution statuses

Output Files

All extracted test data is saved to the extractions/ folder with the following naming convention:

extractions/<TICKET-ID>_<TIMESTAMP>.json

Example: extractions/PROJ-123_2024-01-15T10-30-45-123Z.json

Development

Interactive Setup

Run the setup wizard:

npm run setup

Validate Configuration

Test your Jira connection:

npm run validate

This will:

• Check your .env configuration
• Test connection to Jira
• Verify authentication
• List accessible projects
• Confirm permissions

Build

npm run build

This compiles TypeScript to JavaScript in the build/ directory.

Project Structure

mcp-jira-xray/
├── src/
│   ├── index.ts           # Main MCP server entry point
│   ├── jira-client.ts     # Jira API client
│   ├── config.ts          # Configuration management
│   └── output-handler.ts  # File output handling
├── build/                 # Compiled JavaScript (generated)
├── extractions/           # Output files (generated)
├── .env                   # Environment configuration
├── .env.example           # Example configuration
├── package.json
├── tsconfig.json
└── README.md

Troubleshooting

"Missing required environment variables"

Make sure your .env file exists and contains all required variables (JIRA_HOST, JIRA_EMAIL, JIRA_API_TOKEN).

"Failed to get ticket"

• Verify your Jira credentials are correct
• Check that the ticket ID exists in your Jira instance
• Ensure your API token has appropriate permissions

"Xray API not available"

The server tries multiple methods to extract test data. If Xray-specific APIs aren't available, it falls back to standard Jira JQL queries. This may happen if:

• Xray is not installed on your Jira instance
• Your account doesn't have Xray permissions

Connection Issues

• Ensure your JIRA_HOST includes the protocol (https://)
• Check that your network allows connections to Jira
• Verify your API token is valid and not expired

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Support

For issues and questions:

• Check existing [GitHub Issues](<repository-url>/issues)
• Create a new issue with detailed information
• Include your Jira and Xray versions