Xray MCP

🚀 Xray MCP Server

The Model Context Protocol (MCP) server integrates Xray Cloud APIs with Claude Code and other MCP clients, facilitating seamless interaction and enhanced functionality.

🚀 Quick Start

To quickly get started with the Xray MCP Server, follow the installation steps and configuration instructions provided in the subsequent sections. You'll be able to integrate it with Claude Code and start managing test cases, executions, plans, and sets in no time.

✨ 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)
• 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

📦 Installation

Prerequisites

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

Steps

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 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"
}

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
}

📚 Documentation

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

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

🔧 Technical Details

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/