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 for detailed instructions.

Quick start:

# 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

cd mcp-testrail
npm install

2. Build the Project

npm run build

3. Configure Environment Variables

Create a .env file in the project root:

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)

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

{
  "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:

{
  "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:

// No parameters needed

Response:

[
  {
    "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

# .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

npm run build

Watch Mode (for development)

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
• TestRail API Reference

---

License

MIT