mXray

An MCP (Model Context Protocol) server that connects AI-powered IDEs to Xray Test Management for Jira Cloud. It exposes 28 test management tools over stdio, letting your AI assistant create and manage tests, test executions, test plans, test sets, and import/export test results — all without leaving your editor.

⚠️ Xray Cloud only. This server targets the Xray Cloud REST and GraphQL APIs. Xray Server / Data Center use a different API and are not supported.

Quick Start

# Run directly with npx — no installation needed
JIRA_BASE_URL=https://yourcompany.atlassian.net \
[email protected] \
JIRA_API_TOKEN=your-token \
npx mxray-mcp-server

For IDE integration, see the Usage section below.

Prerequisites

• Node.js ≥ 20.6
• A Jira Cloud account with the Xray for Jira app installed
• A Jira API token — generate one at Atlassian account settings
• (Optional) Xray Cloud API credentials (client ID + secret) — required for Xray-specific tools such as fetching test steps, updating test runs, and importing/exporting results. Generate them in Xray → Settings → API Keys.

Without Xray credentials, 9 Jira-only tools still work fully. The remaining 18 Xray-specific tools will return a clear error message when called.

Installation

# 1. Clone the repository
git clone https://github.com/Timorek/mXray.git
cd mXray

# 2. Install dependencies
npm install

# 3. Configure environment variables
cp .env.example .env
# Edit .env with your credentials (see Configuration below)

# 4. Build
npm run build

Configuration

Edit the .env file created above:

# Required
JIRA_BASE_URL=https://yourcompany.atlassian.net
[email protected]
JIRA_API_TOKEN=your-jira-api-token

# Optional — enables Xray-specific tools (GraphQL, import/export)
XRAY_CLIENT_ID=your-xray-client-id
XRAY_CLIENT_SECRET=your-xray-client-secret

The server validates all variables at startup using strict Zod schemas and exits with a descriptive error if anything is missing or malformed.

Usage

The server communicates over stdio and must be registered with your MCP-compatible IDE. All startup logs are written to stderr to keep the stdio channel clean.

GitHub Copilot CLI

Add to ~/.copilot/mcp-config.json (global) or .copilot/mcp-config.json (project-local):

Option A — via npx with inline credentials (no installation needed):

{
  "mcpServers": {
    "mxray": {
      "command": "npx",
      "args": ["-y", "mxray-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://yourcompany.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-jira-api-token",
        "XRAY_CLIENT_ID": "your-xray-client-id",
        "XRAY_CLIENT_SECRET": "your-xray-client-secret"
      }
    }
  }
}

Option B — via npx loading from .env file (recommended):

Create a .env file with your credentials (see Configuration), then set cwd to the directory containing the .env file (not the file itself):

{
  "mcpServers": {
    "mxray": {
      "command": "npx",
      "args": ["-y", "mxray-mcp-server"],
      "cwd": "/absolute/path/to/mXray"
    }
  }
}

Option C — from local build, inline credentials:

{
  "mcpServers": {
    "mxray": {
      "command": "node",
      "args": ["/absolute/path/to/mXray/dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://yourcompany.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-jira-api-token",
        "XRAY_CLIENT_ID": "your-xray-client-id",
        "XRAY_CLIENT_SECRET": "your-xray-client-secret"
      }
    }
  }
}

Option D — from local build, loading from .env file (recommended):

{
  "mcpServers": {
    "mxray": {
      "command": "node",
      "args": ["--env-file=/absolute/path/to/mXray/.env", "/absolute/path/to/mXray/dist/index.js"]
    }
  }
}

Claude Code

Add to ~/.claude/mcp_settings.json:

Option A — via npx with inline credentials (no installation needed):

{
  "mcpServers": {
    "mxray": {
      "command": "npx",
      "args": ["-y", "mxray-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://yourcompany.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-jira-api-token",
        "XRAY_CLIENT_ID": "your-xray-client-id",
        "XRAY_CLIENT_SECRET": "your-xray-client-secret"
      }
    }
  }
}

Option B — via npx loading from .env file (recommended):

Create a .env file with your credentials (see Configuration), then set cwd to the directory containing the .env file (not the file itself):

{
  "mcpServers": {
    "mxray": {
      "command": "npx",
      "args": ["-y", "mxray-mcp-server"],
      "cwd": "/absolute/path/to/mXray"
    }
  }
}

Option C — from local build, inline credentials:

{
  "mcpServers": {
    "mxray": {
      "command": "node",
      "args": ["/absolute/path/to/mXray/dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://yourcompany.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-jira-api-token",
        "XRAY_CLIENT_ID": "your-xray-client-id",
        "XRAY_CLIENT_SECRET": "your-xray-client-secret"
      }
    }
  }
}

Option D — from local build, loading from .env file (recommended):

{
  "mcpServers": {
    "mxray": {
      "command": "node",
      "args": ["--env-file=/absolute/path/to/mXray/.env", "/absolute/path/to/mXray/dist/index.js"]
    }
  }
}

Available Tools

Tools marked with (Xray) require XRAY_CLIENT_ID and XRAY_CLIENT_SECRET.

Tests

| Tool | Description | |---|---| | list_tests | List tests in a project; filter by label or component | | get_test | Get details of a specific test | | get_test_with_steps | Get test details including manual steps (Xray) | | create_test | Create a test (Manual / Cucumber / Generic) | | update_test | Update test fields (summary, description, labels, priority) | | update_test_type | Change the Xray test type (Xray) | | update_gherkin_test_definition | Update the Gherkin scenario on a Cucumber test (Xray) |

Test Executions

| Tool | Description | |---|---| | list_test_executions | List test executions in a project | | get_test_execution | Get execution details and test runs | | create_test_execution | Create a new test execution | | update_test_run | Update a test run status and comment (Xray) |

Test Plans

| Tool | Description | |---|---| | list_test_plans | List test plans in a project | | get_test_plan | Get plan details and associated tests | | create_test_plan | Create a new test plan | | add_tests_to_test_plan | Add tests to a plan (Xray) |

Test Sets

| Tool | Description | |---|---| | list_test_sets | List test sets in a project | | get_test_set | Get set details and associated tests | | create_test_set | Create a new test set | | add_tests_to_test_set | Add tests to a set (Xray) |

Import

All import tools require Xray credentials.

| Tool | Description | |---|---| | import_execution_results | Import results in Xray JSON format | | import_cucumber_results | Import results in Cucumber JSON format | | import_junit_results | Import results in JUnit XML format | | import_testng_results | Import results in TestNG XML format | | import_nunit_results | Import results in NUnit XML format | | import_robot_results | Import results in Robot Framework XML format | | import_behave_results | Import results in Behave JSON format | | import_feature_file | Import a Gherkin .feature file to create/update tests |

Export

| Tool | Description | |---|---| | export_cucumber_features | Export Cucumber feature files as a base64-encoded ZIP (Xray) |

Sample test report files for testing the import tools are in samples/.

Development

npm run dev         # Run with tsx — no build step needed
npm run build       # Compile TypeScript → dist/
npm run typecheck   # Type-check without emitting files
npm test            # Run tests with Vitest
npm run test:watch  # Run tests in watch mode

To use the dev server in an MCP config, replace node dist/index.js with npx tsx src/index.ts.

Project Structure

mXray/
├── src/
│   ├── index.ts                  # Entry point: config, clients, tool registration
│   ├── types.ts                  # Zod config schema + TypeScript interfaces
│   ├── utils/errors.ts           # Centralized API error formatting
│   ├── services/
│   │   └── XrayCloudService.ts   # Xray JWT auth, GraphQL queries, REST imports
│   └── tools/
│       ├── tests/                # 7 test management tools
│       ├── test-executions/      # 4 test execution tools
│       ├── test-plans/           # 4 test plan tools
│       ├── test-sets/            # 4 test set tools
│       ├── import/               # 8 result import tools
│       └── export/               # 1 export tool
├── samples/                      # Example test report files
├── .env.example                  # Environment variable template
├── package.json
└── tsconfig.json

License

MIT © 2026 Arkadiusz Kłos