mcp-xray-cloud

An MCP (Model Context Protocol) server that connects AI assistants to Xray Cloud for Jira test management.

Manage tests, test plans, executions, and import CI results — all through natural language via Claude or any MCP-compatible client.

Features

Category	Tools
Tests	list_tests, get_test, create_test, update_test
Test Plans	list_test_plans, get_test_plan, create_test_plan, add_tests_to_test_plan
Test Executions	list_test_executions, get_test_execution, create_test_execution
Test Sets	list_test_sets, get_test_set
Test Runs	update_test_run_status
Import Results	Xray JSON, Cucumber, JUnit, TestNG, NUnit, Robot Framework, Behave
Import Features	Gherkin .feature files
Export	Cucumber feature files

Quick Start

git clone https://github.com/remynln/mcp-xray-cloud.git
cd mcp-xray-cloud
npm install
npm run build

Prerequisites

• Node.js 18+
• An Xray Cloud API key pair (how to generate)

Configuration

Set these environment variables:

Variable	Required	Description
XRAY_CLIENT_ID	Yes	Xray Cloud API client ID
XRAY_CLIENT_SECRET	Yes	Xray Cloud API client secret
XRAY_BASE_URL	No	Override API base URL (default: https://xray.cloud.getxray.app)

Usage with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "xray": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-xray-cloud/dist/index.js"],
      "env": {
        "XRAY_CLIENT_ID": "your-client-id",
        "XRAY_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Usage with Claude Code

Add to your .claude.json:

{
  "mcpServers": {
    "xray": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-xray-cloud/dist/index.js"],
      "env": {
        "XRAY_CLIENT_ID": "your-client-id",
        "XRAY_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Tool Reference

Tests

• list_tests — List tests with JQL filtering by project, labels, and component
• get_test — Get full test details including steps and preconditions
• create_test — Create Manual, Cucumber, or Generic tests
• update_test — Update test type (Jira field updates require Jira REST API credentials)

Test Plans

• list_test_plans — List test plans in a project
• get_test_plan — Get test plan details with associated tests
• create_test_plan — Create a new test plan
• add_tests_to_test_plan — Associate tests with a test plan

Test Executions

• list_test_executions — List test executions in a project
• get_test_execution — Get execution details with test run statuses
• create_test_execution — Create an execution, optionally linked to a test plan

Test Runs

• update_test_run_status — Set a test run to PASSED, FAILED, TODO, EXECUTING, or ABORTED

Import Results

• import_execution_results — Xray JSON format
• import_cucumber_results — Cucumber JSON
• import_junit_results — JUnit XML
• import_testng_results — TestNG XML
• import_nunit_results — NUnit XML
• import_robot_results — Robot Framework XML
• import_behave_results — Behave JSON
• import_feature_file — Gherkin .feature file

Export

• export_cucumber_features — Export Cucumber feature files from Xray tests

Project Structure

src/
├── index.ts              # Server entry point
├── client.ts             # Xray Cloud API client (auth + GraphQL + REST)
├── helpers.ts            # Shared formatting utilities
└── tools/
    ├── tests.ts          # Test CRUD tools
    ├── test-plans.ts     # Test plan tools
    ├── test-executions.ts# Test execution tools
    ├── test-sets.ts      # Test set tools
    ├── test-runs.ts      # Test run status updates
    ├── imports.ts        # Result import tools (JSON, XML, Gherkin)
    └── exports.ts        # Feature export tools

Contributing

1. Fork the repo
2. Create a feature branch (git checkout -b feat/my-feature)
3. Run tests (npm test)
4. Commit your changes
5. Open a pull request

License

MIT