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 \
JIRA_EMAIL=you@company.com \
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
JIRA_EMAIL=your-email@company.com
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": "your-email@company.com",
        "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": "your-email@company.com",
        "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": "your-email@company.com",
        "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": "your-email@company.com",
        "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