Xray Cloud MCP for Cursor

A Model Context Protocol server that lets Cursor read and manage Xray Cloud test artifacts — test cases, plans, sets, and executions — directly from the agent.

Authenticates with an Xray Cloud API key only (client ID + secret). No separate Jira API token required.

Xray Cloud only. Does not support Xray Server or Data Center.

Tools

| Tool | Description | |---|---| | get_test_case | Fetch a test case and its steps by Jira issue key | | search_test_cases | Search tests by JQL (keyword, label, status, …) | | get_test_plan | Get a test plan and all tests it contains | | get_test_set | Get a test set and all tests it contains | | get_test_execution_report | Pass/fail summary for a test execution | | get_tests_for_requirement | All tests covering a Jira story or requirement | | create_test_case | Create a new manual test case with steps | | create_test_execution | Create a test execution and add a test case to it | | update_test_run_status | Set PASSED / FAILED / BLOCKED / TODO / EXECUTING on a run |

Prerequisites

• Node.js ≥ 18 on your PATH
• An Xray Cloud API key — in Jira: Xray → Settings → API Keys → create a key → copy the Client ID and Client Secret. Docs

Install from Cursor Marketplace

1. Open Customize in the Cursor sidebar.
2. Search for Xray Cloud and click Install.
3. Set your credentials as environment variables (see below) and restart Cursor.

Manual install

Add to your ~/.cursor/mcp.json or .cursor/mcp.json:

{
  "mcpServers": {
    "xray": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@tzur_avner/xray-mcp"],
      "env": {
        "XRAY_BASE_URL": "https://eu.xray.cloud.getxray.app",
        "XRAY_CLIENT_ID": "YOUR_CLIENT_ID",
        "XRAY_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

Restart Cursor after saving.

Environment variables

| Variable | Required | Default | Description | |---|---|---|---| | XRAY_CLIENT_ID | Yes | — | Xray Cloud API key client ID | | XRAY_CLIENT_SECRET | Yes | — | Xray Cloud API key client secret | | XRAY_BASE_URL | No | https://eu.xray.cloud.getxray.app | Override for US region: https://xray.cloud.getxray.app |

Region note: Xray Cloud is region-partitioned. If your Jira data is in the US region, set XRAY_BASE_URL=https://xray.cloud.getxray.app. The default is EU.

Usage examples

get the test case XSP-684
search for test cases with label "smoke" in project XSP
get all tests in test plan XSP-836
show the execution report for XSP-900
what tests cover story AIR-42?

Verify the connection

After installing, open Tools & MCP (Ctrl+Shift+J) — the xray server should show as connected. If it does not, check Output → MCP Logs.

Attribution

Based on SamtheIII/XRAY-MCP (MIT).

Patches applied:

• Region-aware endpoints via XRAY_BASE_URL (upstream hard-codes US; EU is the default here)
• get_test_plan and get_test_set tools with full pagination (added locally)

License

MIT — see LICENSE.