xray-cloud-mcp

An MCP server for Xray Cloud (test management for Jira).

It lets an MCP client (Claude Code, Claude Desktop, etc.) import automation results and manage

Xray test entities — Tests, Test Executions, and Test Sets — directly.

Tools

The write tools mutate shared Jira/Xray state — review the target before running them.

Credentials

Create an Xray API Key in Jira → Xray → Global Settings → API Keys (for a service user).

This yields a `client_id` + `client_secret`. The server resolves them at startup, **never from a

file on disk**, in this order:

1. Direct env vars `XRAY_CLIENT_ID` + `XRAY_CLIENT_SECRET`, if both are set — simplest for

local use and CI.

2. Azure Key Vault — read from the vault at `XRAY_KEY_VAULT_URL` via

`DefaultAzureCredential`

(`az login` locally, managed identity in Azure). Useful when you don't want secrets in env.

Configuration

> If you only need direct env-var auth, the `@azure/*` dependencies are still installed but never

> invoked. Remove them and the Key Vault branch in `src/config.ts` if you want a leaner build.

Build

npm install
npm run build        # -> dist/
npm run auth-check   # resolves credentials + obtains a token (prints no secret)

Use with an MCP client

Add to your MCP client config (e.g. Claude Code's `.mcp.json` or Claude Desktop's config),

pointing at the built entrypoint:

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

Or, with Azure Key Vault instead of inline secrets:

"env": {
  "XRAY_KEY_VAULT_URL": "https://your-vault.vault.azure.net"
}

Notes

• Description on create: some Jira projects make the Description field mandatory; `create_test`

defaults it to the summary so creation never fails for lack of one.

• Importing results: point `import_execution_junit` at the JUnit XML your test runner produces

(Playwright, Jest, JUnit, etc.). Use `import_execution_xray` for the richer native Xray JSON.

• stdio only: the server speaks MCP over stdio; diagnostics go to stderr (stdout is the

protocol channel).

License

MIT — see LICENSE.