TestRail MCP Server

A Model Context Protocol (MCP) server for TestRail that enables AI assistants (GitHub Copilot, Claude, etc.) to interact with TestRail's test management platform directly from the IDE.

Features

• 27 MCP Tools — Query and manage projects, test cases, runs, results, plans, milestones, and more
• Read & Write — Browse test data and submit results, create runs and cases
• Smart Formatting — AI-friendly output with status summaries, pagination info, and truncation
• Rate Limit Resilient — Automatic retry with exponential backoff on 429 responses
• Reference Data Caching — Statuses, priorities, case types cached for 5 minutes
• VS Code Extension — Self-contained VSIX with bundled server

Quick Start

VS Code Extension

Install VS Code extension TestRail MCP Server VS Code extension that one by fazorboy .

Configuration

Standalone (stdio transport)

# Install
npm install -g @fazorboy/testrail-mcp-server

# Configure
export TESTRAIL_BASE_URL="https://your-instance.testrail.io"
export TESTRAIL_USERNAME="your-email@example.com"
export TESTRAIL_API_KEY="your-api-key"
export TESTRAIL_PROJECT_ID="1"

# Run
testrail-mcp-server

Claude Desktop / MCP Client

Add to your MCP client config:

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["testrail-mcp-server"],
      "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"
      }
    }
  }
}

Configuration

Available Tools

Read-Only (21 tools)

Write (6 tools)

Resources

Prompts

The server includes built-in prompts that guide the AI through multi-step workflows:

Example Prompts

Here are example natural-language prompts you can use with any MCP-compatible AI assistant:

Browsing & Discovery

Show me all active test runs in my project

List all test suites and their sections

Get all test cases in the "Smoke Tests" section

What milestones are coming up?

Show me the section tree for suite "Regression"

Finding Test Cases by Path

Find test cases in suite "xyz", section "AbC > subsection DEF"

List cases in suite "Regression" section "Smoke Tests > Login"

The AI will call find_cases_by_path which resolves the entire path in one step:

1. Finds the suite by name
2. Traverses the section hierarchy to match the path
3. Returns all cases with IDs, titles, and priorities

You can also be explicit about the project:

Find test cases in project 18, suite "xyz", section "ABC > subsection DEF > subsection PQR"

Analyzing Runs & Results

Summarize test run 1234 — what's passing and failing?

Show me all failed tests in run 1234 with their error messages

Get the result history for case C5678 in run 1234

Compare pass rates across all active runs

Submitting Results

Mark cases C101, C102, C103 as passed in run 1234

Create a new test run called "Sprint 15 Smoke" with cases C101-C110

Submit results: C101=passed, C102=failed (login timeout), C103=blocked

Project Management

Give me an overview of project 1 — suites, active runs, milestones

What test plans are currently active?

List all users who can be assigned tests

What custom case fields and statuses are available?

License

MIT