Xray MCP Server

Model Context Protocol (MCP) server to integrate Xray Cloud APIs with Claude Code and other MCP clients.

Features

This MCP server exposes tools to manage test cases and test executions in Xray Cloud using the official GraphQL API:

Test Cases (Test Management)

• create_test_case: Create a new test case (uses GraphQL mutation createTest)
• get_test_case: Retrieve details of a specific test case (uses GraphQL query getTests)
• add_manual_test_steps: Add or update manual test steps for a test case (uses GraphQL mutation updateUnstructuredTestDefinition)
• delete_test_case: Delete a test case (uses GraphQL mutation deleteTest)
• search_test_cases: Search test cases using JQL (Jira Query Language)
• get_project_test_cases: Retrieve all test cases for a project
• update_test_case: ⚠️ Not directly supported - use Jira REST API to update standard fields

Test Executions (Test Automation & CI/CD)

• create_test_execution: Create a new test execution to run tests
• get_test_execution: Retrieve details of a test execution with all test runs
• search_test_executions: Search test executions using JQL
• get_project_test_executions: Retrieve all test executions for a project
• update_test_run_status: Update the status of a test run (PASS, FAIL, etc.)

Test Plans (Test Organization)

• create_test_plan: Create a new test plan to organize tests
• get_test_plan: Retrieve details of a specific test plan with all tests
• search_test_plans: Search test plans using JQL
• get_project_test_plans: Retrieve all test plans for a project
• add_tests_to_test_plan: Add tests to an existing test plan
• remove_tests_from_test_plan: Remove tests from a test plan

Test Sets (Test Grouping)

• create_test_set: Create a new test set to group tests
• get_test_set: Retrieve details of a specific test set with all tests
• search_test_sets: Search test sets using JQL
• get_project_test_sets: Retrieve all test sets for a project
• add_tests_to_test_set: Add tests to an existing test set
• remove_tests_from_test_set: Remove tests from a test set

Prerequisites

• Node.js 18 or higher
• Xray Cloud API credentials (Client ID and Client Secret)

Testing

This project includes comprehensive test coverage:

• Unit Tests: Fast tests with mocked API responses (no credentials needed)
• Integration Tests: End-to-end tests with real Xray Cloud API

# Run unit tests
npm run test:unit

# Run integration tests (requires credentials)
npm run test:integration

# Run all tests
npm test

For detailed testing documentation, see TESTING.md

Installation

1. Clone or download this repository
2. Install dependencies:

npm install

3. Build the project:

npm run build

How to Obtain API Credentials

1. Go to https://xray.cloud.getxray.app/
2. Navigate to Settings → API Keys
3. Click on Create API Key
4. Copy the generated Client ID and Client Secret

Usage

Configuration in Claude Code

To use this MCP server with Claude Code, add the following configuration to your MCP configuration file (typically ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "xray": {
      "command": "node",
      "args": ["/path/to/xray-mcp/dist/index.js"],
      "env": {
        "XRAY_CLIENT_ID": "your_client_id",
        "XRAY_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Important: Replace:

• /path/to/xray-mcp with the absolute path to the project (e.g., /Users/manuel/repositories/xray-mcp)
• your_client_id and your_client_secret with your Xray Cloud credentials

Local Testing

To test the server in development mode:

# Set environment variables
export XRAY_CLIENT_ID="your_client_id"
export XRAY_CLIENT_SECRET="your_client_secret"

# Run the server
npm run dev

Usage Examples

Test Cases

Create a Test Case

{
  "projectKey": "ABC",
  "summary": "Verify login functionality",
  "description": "Test that users can log in with valid credentials",
  "testType": "Manual",
  "labels": ["login", "authentication"],
  "priority": "High"
}

Test Types:

• Manual - Manual tests with structured steps (use with add_manual_test_steps)
• Cucumber - Gherkin/BDD scenarios
• Generic - Other test types
• Generic - Generic automated tests

Add Manual Test Steps

Important: Test cases can use this tool regardless of test type.

{
  "issueId": "58309",
  "steps": [
    {
      "action": "Navigate to login page",
      "data": "URL: https://example.com/login",
      "result": "Login page displays correctly"
    },
    {
      "action": "Enter valid credentials and click login",
      "result": "User is logged in and redirected to dashboard"
    }
  ]
}

Migration from Azure DevOps: This tool is perfect for migrating test cases from ADO:

1. Create test case with testType: "Manual" (default)
2. Use the returned issueId with add_manual_test_steps
3. Steps are formatted as pipe-delimited text: "1. Action|Data|Result"

Search Test Cases

{
  "jql": "project = ABC AND labels = automation",
  "maxResults": 20
}

Retrieve Project Test Cases

{
  "projectKey": "ABC",
  "maxResults": 50
}

Test Executions

Create a Test Execution

{
  "projectKey": "ABC",
  "summary": "Sprint 23 Regression Tests",
  "description": "Regression testing for sprint 23",
  "testIssueIds": ["10001", "10002", "10003"],
  "testEnvironments": ["Chrome", "Firefox"]
}

Retrieve a Test Execution

{
  "testExecutionKey": "ABC-456"
}

Update Test Run Status

{
  "testRunId": "5acc7ab0a3fe1b6fcdc3c737",
  "status": "PASS"
}

Search Recent Test Executions

{
  "jql": "project = ABC AND created >= -7d",
  "maxResults": 20
}

Project Structure

xray-mcp/
├── src/
│   ├── index.ts           # Main MCP server
│   └── xray-client.ts     # Client for Xray Cloud APIs
├── dist/                  # Compiled files (generated after build)
├── .env.example           # Template for environment variables
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md

Xray Cloud APIs

This server uses the following Xray Cloud APIs:

• Authentication: POST /api/v1/authenticate (token valid for 24 hours)
• GraphQL Endpoint: POST /api/v2/graphql
  • Test Queries: getTests - Retrieve tests using JQL
  • Test Mutations: createTest, deleteTest - Create/delete tests
  • Test Execution Queries: getTestExecutions - Retrieve executions using JQL
  • Test Execution Mutations: createTestExecution, updateTestRunStatus - Manage executions and results
  • Test Plan Queries: getTestPlans - Retrieve test plans using JQL
  • Test Plan Mutations: createTestPlan, addTestsToTestPlan, removeTestsFromTestPlan - Manage test plans
  • Test Set Queries: getTestSets - Retrieve test sets using JQL
  • Test Set Mutations: createTestSet, addTestsToTestSet, removeTestsFromTestSet - Manage test sets

For complete API documentation, visit:

• GraphQL API: https://docs.getxray.app/display/XRAYCLOUD/GraphQL+API
• GraphQL Schema: https://us.xray.cloud.getxray.app/doc/graphql/
• REST API: https://docs.getxray.app/display/XRAYCLOUD/REST+API

Use Cases

CI/CD Integration

Use this MCP server to:

1. Automatically create test executions in CI/CD pipelines
2. Update test run statuses based on automated test results
3. Track test execution across different environments
4. Generate test execution reports for sprint reviews

Test Management

Use this MCP server to:

1. Create and organize test cases
2. Search tests using complex JQL queries
3. Manage manual test executions
4. Track test status over time

License

ISC

Support

For issues or questions about Xray Cloud APIs, consult the official documentation:

• https://docs.getxray.app/
• https://support.getxray.app/