Model Context Protocol (MCP) server for Xray Cloud API integration with Claude Code
npm install xray-mcpcreateTest)
getTests)
updateUnstructuredTestDefinition)
deleteTest)
bash
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:
`bash
npm install
`
3. Build the project:
`bash
npm run build
`
$3
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
$3
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):
`json
{
"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
$3
To test the server in development mode:
`bash
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
$3
#### Create a Test Case
`json
{
"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.
`json
{
"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
`json
{
"jql": "project = ABC AND labels = automation",
"maxResults": 20
}
`
#### Retrieve Project Test Cases
`json
{
"projectKey": "ABC",
"maxResults": 50
}
`
$3
#### Create a Test Execution
`json
{
"projectKey": "ABC",
"summary": "Sprint 23 Regression Tests",
"description": "Regression testing for sprint 23",
"testIssueIds": ["10001", "10002", "10003"],
"testEnvironments": ["Chrome", "Firefox"]
}
`
#### Retrieve a Test Execution
`json
{
"testExecutionKey": "ABC-456"
}
`
#### Update Test Run Status
`json
{
"testRunId": "5acc7ab0a3fe1b6fcdc3c737",
"status": "PASS"
}
`
#### Search Recent Test Executions
`json
{
"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