@tzur_avner/xray-mcp

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.