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

Clone or download this repository
Install dependencies:

npm install

Build the project:

npm run build

How to Obtain API Credentials

Go to https://xray.cloud.getxray.app/
Navigate to Settings → API Keys
Click on Create API Key
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"
}

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:

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

Test Management

Use this MCP server to:

Create and organize test cases
Search tests using complex JQL queries
Manage manual test executions
Track test status over time

License

ISC

Support

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

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

Clone or download this repository
Install dependencies:

npm install

Build the project:

npm run build

How to Obtain API Credentials

Go to https://xray.cloud.getxray.app/
Navigate to Settings → API Keys
Click on Create API Key
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"
}

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:

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

Test Management

Use this MCP server to:

Create and organize test cases
Search tests using complex JQL queries
Manage manual test executions
Track test status over time

License

ISC

Support

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