testrail-mcp-server
Provides tools for managing TestRail projects, test cases, test runs, test results, and sections.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@testrail-mcp-server List all TestRail projects"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
TestRail MCP Server
A Model Context Protocol (MCP) server for TestRail integration, providing comprehensive access to TestRail's test management functionality through MCP tools.
Features
This MCP server provides tools for:
Projects: List and retrieve TestRail projects
Test Cases: Create, read, update, and delete test cases
Test Runs: Manage test runs (create, update, close, delete)
Test Results: Add and retrieve test results (single and bulk operations)
Sections: Organize test cases with sections
Related MCP server: TestRail MCP Server
Prerequisites
Node.js 18 or higher
A TestRail instance with API access
TestRail API key (generate from your TestRail account settings)
Installation
Clone or download this repository
Install dependencies:
npm installBuild the project:
npm run buildCreate a
.envfile in the project root with your TestRail credentials:
cp .env.example .envEdit .env with your credentials:
TESTRAIL_URL=https://your-instance.testrail.io
TESTRAIL_USERNAME=your-email@example.com
TESTRAIL_API_KEY=your-api-keyConfiguration for Claude Code
To use this MCP server with Claude Code, add it to your MCP settings file:
macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"testrail": {
"command": "node",
"args": ["/absolute/path/to/testrail-mcp-server/dist/index.js"],
"env": {
"TESTRAIL_URL": "https://your-instance.testrail.io",
"TESTRAIL_USERNAME": "your-email@example.com",
"TESTRAIL_API_KEY": "your-api-key"
}
}
}
}Or if you prefer to use the .env file:
{
"mcpServers": {
"testrail": {
"command": "node",
"args": ["/absolute/path/to/testrail-mcp-server/dist/index.js"]
}
}
}Available Tools
Projects
testrail_get_projects- Get all projectstestrail_get_project- Get a specific project by ID
Test Cases
testrail_get_cases- Get test cases from a project (optionally filtered by suite)testrail_get_case- Get a specific test case by IDtestrail_add_case- Create a new test case in a sectiontestrail_update_case- Update an existing test casetestrail_delete_case- Delete a test case
Test Runs
testrail_get_runs- Get all test runs in a projecttestrail_get_run- Get a specific test run by IDtestrail_add_run- Create a new test runtestrail_update_run- Update an existing test runtestrail_close_run- Close a test runtestrail_delete_run- Delete a test run
Test Results
testrail_get_results- Get test results for a specific testtestrail_get_results_for_case- Get test results for a test case in a runtestrail_get_results_for_run- Get all test results for a test runtestrail_add_result- Add a test result for a specific testtestrail_add_result_for_case- Add a test result for a case in a test runtestrail_add_results- Add multiple test results (bulk operation)testrail_add_results_for_cases- Add multiple test results for cases (bulk operation)
Sections
testrail_get_sections- Get sections from a project (optionally filtered by suite)testrail_get_section- Get a specific section by IDtestrail_add_section- Create a new sectiontestrail_update_section- Update an existing sectiontestrail_delete_section- Delete a section
Usage Examples
Once configured, you can use these tools through Claude Code. Here are some example prompts:
Getting Projects
List all TestRail projectsCreating a Test Case
Create a new test case in section 123 with title "Test user login" and priority HighAdding Test Results
Add a passed test result for test case 456 in run 789 with comment "All checks passed"Creating a Test Run
Create a new test run called "Sprint 24 Testing" for project 1TestRail Status IDs
When adding test results, use these status IDs:
1- Passed2- Blocked3- Untested (retest)4- Retest5- Failed
TestRail Priority IDs
When creating or updating test cases, use these priority IDs:
1- Low2- Medium3- High4- Critical
Development
Project Structure
testrail-mcp-server/
├── src/
│ ├── index.ts # Main MCP server implementation
│ └── testrail-client.ts # TestRail API client
├── dist/ # Compiled JavaScript output
├── package.json
├── tsconfig.json
├── .env.example
└── README.mdBuilding
npm run buildWatching for Changes
npm run watchRunning Locally
npm startTroubleshooting
Connection Issues
Verify your TestRail credentials are correct
Check that your TestRail instance URL is accessible
Ensure your API key has the necessary permissions
Check the Claude Code logs for detailed error messages
API Errors
401 Unauthorized: Invalid credentials or API key
403 Forbidden: Insufficient permissions for the requested operation
404 Not Found: Resource (project, case, run, etc.) not found
429 Too Many Requests: Rate limit exceeded, wait and retry
API Reference
For more details on TestRail's API, see the official TestRail API documentation.
License
MIT
Contributing
Contributions are welcome! Please feel free to submit issues or pull requests.
Security
Never commit your .env file or expose your TestRail API credentials. Always use environment variables or secure credential storage.
Available Tools
25 toolstestrail_add_caseC
Create a new test case in a section
Inputs: title (required), section_id (required), refs, type_id, +6 more.
testrail_add_resultB
Add a test result for a specific test
Inputs: test_id (required), status_id (required), comment, defects, +3 more.
testrail_add_result_for_caseC
Add a test result for a case in a specific test run
Inputs: run_id (required), case_id (required), status_id (required), comment, +4 more.
testrail_add_resultsB
Add multiple test results for a test run (bulk operation)
Inputs: run_id (required), results (required).
testrail_add_results_for_casesC
Add multiple test results for cases in a test run (bulk operation)
Inputs: run_id (required), results (required).
testrail_add_runC
Create a new test run
Inputs: name (required), project_id (required), case_ids, suite_id, +4 more.
testrail_add_sectionC
Create a new section in a project
Inputs: name (required), project_id (required), suite_id, parent_id, +1 more.
testrail_close_runC
Close a test run
Inputs: run_id (required).
testrail_delete_caseC
Delete a test case
Inputs: case_id (required).
testrail_delete_runC
Delete a test run
Inputs: run_id (required).
testrail_delete_sectionC
Delete a section
Inputs: section_id (required).
testrail_get_caseC
Get a specific test case by ID
Inputs: case_id (required).
testrail_get_casesC
Get test cases from a project (optionally filtered by suite)
Inputs: project_id (required), suite_id.
testrail_get_projectB
Get a specific project by ID
Inputs: project_id (required).
testrail_get_projectsB
Get all projects from TestRail
Inputs: no named parameters.
testrail_get_resultsC
Get test results for a specific test
Inputs: test_id (required), limit.
testrail_get_results_for_caseB
Get test results for a specific test case in a run
Inputs: run_id (required), case_id (required), limit.
testrail_get_results_for_runC
Get all test results for a test run
Inputs: run_id (required), limit.
testrail_get_runC
Get a specific test run by ID
Inputs: run_id (required).
testrail_get_runsB
Get all test runs in a project
Inputs: project_id (required).
testrail_get_sectionB
Get a specific section by ID
Inputs: section_id (required).
testrail_get_sectionsB
Get sections from a project (optionally filtered by suite)
Inputs: project_id (required), suite_id.
testrail_update_caseC
Update an existing test case
Inputs: case_id (required), refs, title, estimate, +4 more.
testrail_update_runC
Update an existing test run
Inputs: run_id (required), name, description, milestone_id.
testrail_update_sectionC
Update an existing section
Inputs: section_id (required), name, description.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 25 tools
Most tools are clearly distinct by resource and action, but the result-related tools (testrail_get_results, testrail_get_results_for_case, testrail_get_results_for_run, testrail_add_result, testrail_add_result_for_case, testrail_add_results, testrail_add_results_for_cases) have subtle differences that may cause confusion. The bulk vs single and for_case vs for_run distinctions are not immediately obvious from names alone.
All tools follow a consistent pattern: testrail_<verb>_<resource> (e.g., testrail_get_project, testrail_add_case). The prefix is uniform, verbs are consistent (get, add, update, delete), and resources are clear. Minor variations like 'get_results_for_case' are still predictable.
25 tools is on the higher end and might feel heavy, but it covers a broad domain (projects, cases, runs, results, sections). However, some tools could be consolidated (e.g., result retrieval and addition variants) to reduce redundancy. The count is borderline but justified by the comprehensive CRUD operations.
The surface covers core entities (projects, cases, runs, results, sections) with full CRUD for cases, runs, and sections. However, projects only have get operations (no create/update/delete), and there is no tool for retrieving a single test result by ID. These are minor gaps that agents can work around by using list operations.
Maintenance
Related MCP Connectors
Create and manage test cases, test runs and results in Testiny from your AI assistant.
Official MCP server for Qase — manage test cases, runs, suites, defects via AI tools.
Free test management over MCP: projects, test cases, plans, runs, environments and tasks.
Run, debug, and triage tests from your IDE using natural language, no dashboard switching, no manual data transfers. The TestMu AI (formerly LambdaTest) MCP Server is a single remote server exposing four tool suites: HyperExecute — analyze your project, generate YAML configs and test runner commands, then monitor jobs and sessions. Automation — pull a TestID's details plus command, network, and console logs into one chat for instant root-cause analysis. Includes mobile app upload. SmartUI — explain pixel, layout, DOM, and perceptual changes in a visual regression run, with context-aware React/HTML/CSS fixes. Accessibility — audit any public URL or a local React app against WCAG and get ready-to-apply remediation steps. Connects over https://mcp.lambdatest.com/mcp using OAuth 2.1 — no API keys in your config. One-click install in Cursor; works with Claude, GitHub Copilot, Cline, and any MCP client. Tests execute on the TestMu AI cloud: 3,000+ browsers and 10,000+ real devices.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to interact with TestRail test management systems through comprehensive API integration. Supports retrieving and updating test cases, projects, suites, runs, and results, plus adding attachments and managing test data through natural language commands.1831 npmMIT
- AlicenseAqualityFmaintenanceEnables management of TestRail projects, test cases, runs, and results directly through MCP-supported clients. It provides a comprehensive set of tools to interact with the TestRail API for seamless test cycle management within AI environments.426,218 npm42MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for TestRail that enables AI assistants to interact with TestRail's test management platform. It can query and manage projects, test cases, runs, results, plans, milestones, and more.MIT
- AlicenseAqualityDmaintenanceMCP server for TestRail that enables AI agents to manage test cases, runs, and results, plus a bundled skill to convert Jira tickets into TestRail test cases.15MIT