Enables querying and management of TestRail's test management platform, allowing users to browse test cases, submit results, and manage projects, runs, plans, and milestones.
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 |
|
| Yes | — | TestRail API key (generate at My Settings > API Keys) |
|
| Yes | — | TestRail instance URL (e.g., |
|
| Yes | — | TestRail username (email address) |
|
| Yes | — | Default project ID (used when not specified in tool params) |
|
| No |
| HTTP request timeout in milliseconds |
|
| No |
| Default page size for list queries (max 250) |
|
| No |
| Enable disk caching for semi-static TestRail data |
|
| No |
| Cache time-to-live in hours |
|
| No |
| 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="your-email@example.com"
export TESTRAIL_API_KEY="your-api-key"
export TESTRAIL_PROJECT_ID="1"
# Run
testrail-mcp-serverClaude 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
Variable | Required | Default | Description |
| Yes | — | TestRail instance URL |
| Yes | — | TestRail username (email) |
| Yes | — | TestRail API key |
| Yes | — | Default project ID (tools auto-use this when project_id is omitted) |
| No |
| HTTP request timeout |
| No |
| Default page size (max 250) |
Available Tools
Read-Only (21 tools)
Tool | Description |
| List all projects |
| Get project details |
| List test cases (filterable by suite, section, priority, type) |
| Get case details with steps |
| Find test cases by suite name + section path (resolves IDs automatically) |
| List test runs |
| Get run details with status counts |
| Get results for a run |
| Get result history for a case in a run |
| List tests in a run |
| List test plans |
| Get plan details with entries |
| List milestones |
| Get available statuses |
| Get priorities |
| Get case types |
| Get case custom fields |
| Get result custom fields |
| Get case templates |
| List users |
| List test suites |
| List sections (folder tree) |
Write (6 tools)
Tool | Description |
| Submit a test result |
| Bulk submit results |
| Create a test run |
| Close/archive a run |
| Create a test case |
| Update a test case |
Resources
URI | Description |
| Server health check |
| Project dashboard |
Prompts
The server includes built-in prompts that guide the AI through multi-step workflows:
Prompt | Description |
| Navigate TestRail hierarchy (Project > Suite > Section) to find cases |
| Get comprehensive run summary with failure analysis |
| Full project dashboard with suites, runs, milestones |
| 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:
Finds the suite by name
Traverses the section hierarchy to match the path
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 runsSubmitting 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=blockedProject 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?