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

Test Executions

Test Plans

Test Sets

Import

All import tools require Xray credentials.

Export

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