Submit
bhayanak

TestRail MCP Server

Community bhayanak
Updated

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

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

Setting (VS Code) Env Var Required Default Description
testrailMcp.apiKey TESTRAIL_API_KEY Yes — TestRail API key (generate at My Settings > API Keys)
testrailMcp.baseUrl TESTRAIL_BASE_URL Yes — TestRail instance URL (e.g., https://company.testrail.io)
testrailMcp.username TESTRAIL_USERNAME Yes — TestRail username (email address)
testrailMcp.projectId TESTRAIL_PROJECT_ID Yes — Default project ID (used when not specified in tool params)
testrailMcp.timeout TESTRAIL_TIMEOUT_MS No 30000 HTTP request timeout in milliseconds
testrailMcp.maxResults TESTRAIL_MAX_RESULTS No 250 Default page size for list queries (max 250)
testrailMcp.cacheEnabled TESTRAIL_CACHE_ENABLED No true Enable disk caching for semi-static TestRail data
testrailMcp.cacheTtlHours TESTRAIL_CACHE_TTL_HOURS No 168 (7 days) Cache time-to-live in hours
testrailMcp.cacheDir TESTRAIL_CACHE_DIR No ~/.testrail-mcp-cache Directory for disk cache files

Standalone (stdio transport)

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

# Configure
export TESTRAIL_BASE_URL="https://your-instance.testrail.io"
export TESTRAIL_USERNAME="[email protected]"
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": "[email protected]",
        "TESTRAIL_API_KEY": "your-api-key",
        "TESTRAIL_PROJECT_ID": "1"
      }
    }
  }
}

Configuration

Variable Required Default Description
TESTRAIL_BASE_URL Yes — TestRail instance URL
TESTRAIL_USERNAME Yes — TestRail username (email)
TESTRAIL_API_KEY Yes — TestRail API key
TESTRAIL_PROJECT_ID Yes — Default project ID (tools auto-use this when project_id is omitted)
TESTRAIL_TIMEOUT_MS No 30000 HTTP request timeout
TESTRAIL_MAX_RESULTS No 250 Default page size (max 250)

Available Tools

Read-Only (21 tools)

Tool Description
get_projects List all projects
get_project Get project details
get_cases List test cases (filterable by suite, section, priority, type)
get_case Get case details with steps
find_cases_by_path Find test cases by suite name + section path (resolves IDs automatically)
get_runs List test runs
get_run Get run details with status counts
get_results_for_run Get results for a run
get_results_for_case Get result history for a case in a run
get_tests List tests in a run
get_plans List test plans
get_plan Get plan details with entries
get_milestones List milestones
get_statuses Get available statuses
get_priorities Get priorities
get_case_types Get case types
get_case_fields Get case custom fields
get_result_fields Get result custom fields
get_templates Get case templates
get_users List users
get_suites List test suites
get_sections List sections (folder tree)

Write (6 tools)

Tool Description
add_result_for_case Submit a test result
add_results_for_cases Bulk submit results
add_run Create a test run
close_run Close/archive a run
add_case Create a test case
update_case Update a test case

Resources

URI Description
testrail://health Server health check
testrail://project/{id}/summary Project dashboard

Prompts

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

Prompt Description
find_test_cases Navigate TestRail hierarchy (Project > Suite > Section) to find cases
test_run_summary Get comprehensive run summary with failure analysis
project_overview Full project dashboard with suites, runs, milestones
submit_test_results Submit results for multiple cases in a run

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

MCP Server · Populars

MCP Server · New