# TestRail MCP Server

A Model Context Protocol (MCP) server that integrates TestRail with Claude Code, enabling AI-assisted test management workflows.

## Features

- **Project Management**: List and retrieve TestRail projects
- **Suite Management**: Access test suites and their configurations
- **Test Case Operations**: Retrieve, update, and manage test cases
- **Test Run Creation**: Create and manage test runs
- **Results Tracking**: Add test results and retrieve execution history
- **Automation Integration**: Link automated tests to TestRail cases

## Prerequisites

- Node.js 18.x or higher
- npm or pnpm
- TestRail instance with API access enabled
- TestRail user account with appropriate permissions

## Installation

### Option 1: Using Pre-built Container (Recommended)

The easiest way to use the TestRail MCP server is via the pre-built container. See [CONTAINER.md](./CONTAINER.md) for detailed instructions.

**Quick start:**
```bash
# Pull the container
podman pull ghcr.io/yshpyluk/mcp-testrail:latest

# Configure in .mcp.json (see CONTAINER.md for full setup)
```

### Option 2: Local Installation

1. **Clone and Install Dependencies**

```bash
cd mcp-testrail
npm install
```

2. **Build the Project**

```bash
npm run build
```

3. **Configure Environment Variables**

Create a `.env` file in the project root:

```env
TESTRAIL_BASE_URL=https://your-instance.testrail.io
TESTRAIL_USERNAME=your-email@example.com
TESTRAIL_API_KEY=your-api-key
TESTRAIL_PROJECT_ID=1  # REQUIRED: The TestRail project to work with
```

**Getting Your TestRail API Key:**

1. Log in to TestRail
2. Go to **My Settings** (top-right corner)
3. Click on **API Keys** tab
4. Click **Add Key** to generate a new API key
5. Copy the generated key (you won't be able to see it again)

**Configuring Your Project**

`TESTRAIL_PROJECT_ID` is **required** - this MCP server is designed to work with a single TestRail project. All operations will be performed on the configured project. To find your project ID, check the URL when viewing your project in TestRail (e.g., `.../index.php?/projects/overview/1` - the ID is `1`).

## Configuration for Claude Code

Add the TestRail MCP server to your Claude Code configuration:

### Option 1: Global Configuration (~/.config/claude/config.json)

```json
{
  "mcpServers": {
    "testrail": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-testrail/dist/index.js"],
      "env": {
        "TESTRAIL_BASE_URL": "https://your-instance.testrail.io",
        "TESTRAIL_USERNAME": "your-email@example.com",
        "TESTRAIL_API_KEY": "your-api-key",
        "TESTRAIL_PROJECT_ID": "1"
      }
    }
  }
}
```

### Option 2: Project-Level Configuration (.mcp.json in project root)

```json
{
  "mcpServers": {
    "testrail": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-testrail/dist/index.js"],
      "env": {
        "TESTRAIL_BASE_URL": "https://your-instance.testrail.io",
        "TESTRAIL_USERNAME": "your-email@example.com",
        "TESTRAIL_API_KEY": "your-api-key",
        "TESTRAIL_PROJECT_ID": "1"
      }
    }
  }
}
```

**Security Note:** For production use, consider using environment variables instead of hardcoding credentials:

```json
{
  "mcpServers": {
    "testrail": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-testrail/dist/index.js"],
      "env": {
        "TESTRAIL_BASE_URL": "${TESTRAIL_BASE_URL}",
        "TESTRAIL_USERNAME": "${TESTRAIL_USERNAME}",
        "TESTRAIL_API_KEY": "${TESTRAIL_API_KEY}",
        "TESTRAIL_PROJECT_ID": "${TESTRAIL_PROJECT_ID}"
      }
    }
  }
}
```

## Available Tools

### Project Operations

#### `list_projects`
Get all TestRail projects.

**Example:**
```typescript
// No parameters needed
```

**Response:**
```json
[
  {
    "id": 1,
    "name": "Akrochem ERP",
    "is_completed": false,
    "suite_mode": 1,
    "url": "https://your-instance.testrail.io/index.php?/projects/overview/1"
  }
]
```

#### `get_project`
Get the configured TestRail project details.

**Parameters:** None

---

### Suite Operations

#### `list_suites`
Get all test suites for the configured project.

**Parameters:** None

#### `get_suite`
Get a specific test suite by ID.

**Parameters:**
- `suite_id` (number): The ID of the suite

---

### Test Case Operations

#### `list_test_cases`
Get test cases for the configured project, optionally filtered by suite.

**Parameters:**
- `suite_id` (number, optional): Filter by suite ID

**Example:**
```typescript
{
  "suite_id": 5
}
```

#### `get_test_case`
Get a specific test case by ID.

**Parameters:**
- `case_id` (number): The ID of the test case

#### `update_test_case`
Update a test case with new information.

**Parameters:**
- `case_id` (number): The ID of the test case
- `title` (string, optional): New title
- `custom_automation_id` (string, optional): Automation identifier
- `refs` (string, optional): Reference IDs (e.g., "JIRA-123")
- `priority_id` (number, optional): Priority (1=Low, 2=Medium, 3=High, 4=Critical)

**Example:**
```typescript
{
  "case_id": 100,
  "custom_automation_id": "tests/specs/ui/purchase-order/new-po-page.spec.ts",
  "refs": "AK-1234"
}
```

---

### Test Run Operations

#### `create_test_run`
Create a new test run in the configured project.

**Parameters:**
- `suite_id` (number): The ID of the test suite
- `name` (string): Name of the test run
- `description` (string, optional): Description
- `case_ids` (number[], optional): Specific test cases to include (omit for all cases)

**Example:**
```typescript
{
  "suite_id": 5,
  "name": "Automated Regression - 2025-01-08",
  "description": "Nightly automated test run",
  "case_ids": [100, 101, 102]
}
```

#### `list_test_runs`
Get test runs for the configured project.

**Parameters:**
- `suite_id` (number, optional): Filter by suite ID

#### `get_test_run`
Get a specific test run by ID.

**Parameters:**
- `run_id` (number): The ID of the test run

#### `close_test_run`
Close a test run (mark as completed).

**Parameters:**
- `run_id` (number): The ID of the test run

---

### Test Results Operations

#### `add_test_results`
Add test results for multiple test cases.

**Status IDs:**
- `1` = Passed
- `2` = Blocked
- `3` = Untested
- `4` = Retest
- `5` = Failed

**Parameters:**
- `run_id` (number): The ID of the test run
- `results` (array): Array of test result objects

**Result Object:**
- `case_id` (number): Test case ID
- `status_id` (number): Status (1-5)
- `comment` (string, optional): Test result comment
- `version` (string, optional): Version/build tested
- `elapsed` (string, optional): Time elapsed (e.g., "1m 30s")
- `defects` (string, optional): Comma-separated defect IDs

**Example:**
```typescript
{
  "run_id": 50,
  "results": [
    {
      "case_id": 100,
      "status_id": 1,
      "comment": "Test passed successfully",
      "version": "v2.5.0",
      "elapsed": "45s"
    },
    {
      "case_id": 101,
      "status_id": 5,
      "comment": "Timeout waiting for element",
      "defects": "JIRA-456"
    }
  ]
}
```

#### `get_test_results`
Get all test results for a test run.

**Parameters:**
- `run_id` (number): The ID of the test run

---

## Usage Examples with Claude Code

### Example 1: Create Test Run from Playwright Execution

```
Create a test run in TestRail for the upcoming automated test execution:
- Suite: UI Tests (ID: 5)
- Name: "Automated Regression - [TODAY'S DATE]"
- Include all test cases from the suite
```

### Example 2: Push Test Results from CI/CD

```
Add test results to TestRail run #50:
- Case 100: Passed (45s)
- Case 101: Failed - "Timeout waiting for selector" (link to JIRA-456)
- Case 102: Passed (1m 20s)
```

### Example 3: Sync Automation IDs

```
Update test cases with automation IDs based on our Playwright test files:
- Case 100 -> tests/specs/ui/purchase-order/new-po-page.spec.ts
- Case 101 -> tests/specs/ui/purchase-order/uom-validation.spec.ts
```

### Example 4: Generate Test Coverage Report

```
List all test cases in suite 5 and compare with our Playwright test files.
Create a coverage report showing which TestRail cases have automated tests.
```

---

## Integration Patterns

### Pattern 1: CI/CD Integration

Use the TestRail MCP server in GitHub Actions or other CI/CD pipelines:

```yaml
# .github/workflows/playwright-testrail.yml
- name: Run Tests and Report to TestRail
  run: |
    # Run Playwright tests
    npx playwright test --reporter=json > test-results.json

    # Use Claude Code to parse results and push to TestRail
    claude-code "Parse test-results.json and create TestRail run with results"
```

### Pattern 2: Manual Test Run Creation

```
Create a test run for Sprint 23 smoke tests:
- Include only priority 4 (Critical) test cases
- Name: "Sprint 23 - Smoke Tests"
```

### Pattern 3: Test Case Management

```
Update all purchase order test cases to link to Jira epic AK-1000
```

### Pattern 4: Results Analysis

```
Get test results for the last 5 runs and identify flaky tests
(cases that have inconsistent pass/fail status)
```

---

## Development

### Build

```bash
npm run build
```

### Watch Mode (for development)

```bash
npm run watch
```

### Project Structure

```
mcp-testrail/
├── src/
│   ├── index.ts              # Main MCP server implementation
│   └── testrail-client.ts    # TestRail API client wrapper
├── dist/                      # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md
```

---

## Troubleshooting

### "Error: Missing required environment variables"

Ensure `TESTRAIL_BASE_URL`, `TESTRAIL_USERNAME`, and `TESTRAIL_API_KEY` are set in your MCP configuration.

### "Error: 401 Unauthorized"

Check that:
- Your API key is correct
- Your TestRail username is correct
- API access is enabled in your TestRail instance (Admin > Site Settings > API)

### "Error: Cannot find module"

Run `npm run build` to compile TypeScript to JavaScript.

### "Connection refused"

Verify your `TESTRAIL_BASE_URL` is correct and accessible from your network.

---

## Security Best Practices

1. **Never commit API keys** to version control
2. **Use environment variables** for sensitive credentials
3. **Limit API key permissions** to only what's needed
4. **Rotate API keys** regularly
5. **Use project-level .mcp.json** for team-specific configurations

---

## TestRail API Reference

For more details on TestRail API capabilities:
- [TestRail API Documentation](https://www.gurock.com/testrail/docs/api)
- [TestRail API Reference](https://www.gurock.com/testrail/docs/api/reference)

---

## License

MIT