xray

The Xray MCP Server provides a set of tools that bridge Xray Cloud APIs with MCP clients, allowing you to manage test cases, test executions, test plans, and test sets from Claude Code or other MCP clients. It exposes GraphQL-backed operations such as creating, retrieving, updating, and deleting test cases; creating and updating test executions; and organizing tests into plans and sets. The server authenticates with Xray Cloud using an API key-based flow (client ID and client secret) and then communicates with Xray's GraphQL and REST endpoints to perform the requested operations. Typical use cases include integrating test management into CI/CD pipelines, running automated test executions, and querying test data across projects.

To use the MCP server, configure it in your MCP client with the proper command and environment. The server expects XRAY_CLIENT_ID and XRAY_CLIENT_SECRET to be available as environment variables. Once running, you can invoke the provided tools via MCP to create and manage tests, executions, plans, and sets, or to search using JQL-like queries supported by the underlying GraphQL API. The server translates MCP calls into Xray Cloud GraphQL/REST requests and returns structured results suitable for your MCP client workflows.

Prerequisites:

• Node.js 18 or higher
• npm (comes with Node.js) or npm/yarn
• Access to Xray Cloud API credentials (Client ID and Client Secret)

Installation steps:

# 1. Clone or download this repository
git clone https://github.com/your-org/xray-mcp.git
cd xray-mcp

# 2. Install dependencies
npm install

# 3. Build the project (if a build step exists)
npm run build

Configuration (example):

# Create or edit your MCP config for Claude Code or your MCP client
# Example path assumed: ~/Library/Application Support/Claude/claude_desktop_config.json

Environment setup:

# Set credentials (keep these secret; do not commit to repo)
export XRAY_CLIENT_ID="your_client_id"
export XRAY_CLIENT_SECRET="your_client_secret"

Run the server (in development or after building):

# If using npm script for dev
npm run dev

# Or run the built entry point directly if applicable
node dist/index.js

Notes:

• Ensure the path in the MCP config matches where index.js or the built artifact resides.
• If you modify credentials, restart the MCP server to pick up changes.

Tips and common issues:

• Make sure XRAY_CLIENT_ID and XRAY_CLIENT_SECRET are valid and have the required permissions in Xray Cloud.
• The server exposes operations for Test Cases, Test Executions, Test Plans, and Test Sets via GraphQL; use the corresponding MCP actions (create, get, search, add/remove) as described in the README.
• When updating fields that are read-only through GraphQL (or require REST), use the supported endpoints as noted in the docs (e.g., update_test_case uses Jira REST API for standard fields).
• If you encounter authentication failures, verify that API keys are active and that the clock on your environment is synchronized (token issuance may be time-bound).
• For local testing, you can export credentials in your shell; in production, consider a secret store or environment management system.
• Review the Xray Cloud GraphQL and REST API docs for specifics on mutation/query names and required input shapes.