TestRail MCP Server
A Model Context Protocol (MCP) server for seamless TestRail integration. This server enables AI assistants like Claude, Cursor, and other MCP-compatible clients to interact directly with your TestRail instance.
Features
- 🔐 Secure Authentication - API key-based authentication with TestRail
- 📊 Full TestRail API Coverage - Support for TestRail API v9.7.2
- 🚀 Easy Integration - Works with Cursor, Claude Desktop, and other MCP clients
- 📦 Zero Configuration - Run directly with
npx
Installation
Global Installation
npm i -g @tenbarrel6/testrail-mcp
Local Installation
npm i @tenbarrel6/testrail-mcp
Using npx
No installation required - run directly in downloaded github repository:
npx @tenbarrel6/testrail-mcp
Configuration
Environment Variables
Create a .env file in your project root or set environment variables:
TESTRAIL_URL=https://your-domain.testrail.io
TESTRAIL_USERNAME=your-email@example.com
TESTRAIL_API_KEY=your-api-key-here
Cursor IDE Configuration
Add to your Cursor settings (.cursor/mcp.json or global settings):
{
"mcpServers": {
"testrail": {
"command": "npx",
"args": ["-y", "@tenbarrel6/testrail-mcp"],
"env": {
"TESTRAIL_URL": "https://your-company.testrail.io",
"TESTRAIL_USERNAME": "your-email@company.com",
"TESTRAIL_API_KEY": "your-api-key-here"
}
}
}
}
Claude Desktop Configuration
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"testrail": {
"command": "npx",
"args": ["-y", "@tenbarrel6/testrail-mcp"],
"env": {
"TESTRAIL_URL": "https://your-company.testrail.io",
"TESTRAIL_USERNAME": "your-email@company.com",
"TESTRAIL_API_KEY": "your-api-key-here"
}
}
}
}
Getting Your TestRail API Key
- Log in to your TestRail instance
- Go to My Settings (click your name in the top right)
- Navigate to the API Keys tab
- Click Add Key to generate a new API key
- Copy and save the key securely
Projects
| Tool | Description |
|---|
get_projects | Get all TestRail projects |
get_project | Get a specific project by ID |
Test Suites
| Tool | Description |
|---|
get_suites | Get all test suites for a project |
get_suite | Get a specific test suite by ID |
add_suite | Create a new test suite |
update_suite | Update an existing test suite |
Sections
| Tool | Description |
|---|
get_sections | Get all sections for a project/suite |
get_section | Get a specific section by ID |
add_section | Create a new section |
update_section | Update an existing section |
delete_section | Delete a section |
move_section | Move a section to another parent or position |
Test Cases
| Tool | Description |
|---|
get_cases | Get test cases for a project/suite |
get_case | Get a specific test case by ID |
add_case | Create a new test case |
update_case | Update an existing test case |
delete_case | Delete a test case |
delete_cases | Delete multiple test cases |
copy_cases_to_section | Copy test cases to another section |
move_cases_to_section | Move test cases to another section |
get_case_types | Get all available test case types |
get_case_fields | Get all available test case fields |
get_history_for_case | Get the edit history for a test case |
Test Runs
| Tool | Description |
|---|
get_runs | Get test runs for a project |
get_run | Get a specific test run by ID |
add_run | Create a new test run |
update_run | Update an existing test run |
close_run | Close a test run |
delete_run | Delete a test run |
Tests
| Tool | Description |
|---|
get_tests | Get tests for a test run |
get_test | Get a specific test by ID |
Results
| Tool | Description |
|---|
get_results | Get results for a test |
get_results_for_case | Get results for a test case in a run |
get_results_for_run | Get all results for a test run |
add_result | Add a test result |
add_result_for_case | Add a test result for a specific case in a run |
add_results | Add multiple test results by test IDs |
add_results_for_cases | Add multiple test results for cases in a run |
Test Plans
| Tool | Description |
|---|
get_plans | Get test plans for a project |
get_plan | Get a specific test plan by ID |
add_plan | Create a new test plan |
update_plan | Update an existing test plan |
close_plan | Close a test plan |
delete_plan | Delete a test plan |
add_plan_entry | Add test runs to a test plan |
update_plan_entry | Update a test plan entry |
delete_plan_entry | Delete a test plan entry |
add_run_to_plan_entry | Add a test run to an existing plan entry |
update_run_in_plan_entry | Update a test run inside a plan entry |
delete_run_from_plan_entry | Delete a test run from a plan entry |
Milestones
| Tool | Description |
|---|
get_milestones | Get milestones for a project |
get_milestone | Get a specific milestone by ID |
add_milestone | Create a new milestone |
update_milestone | Update an existing milestone |
delete_milestone | Delete a milestone |
Users
| Tool | Description |
|---|
get_users | Get all users (optionally filtered by project) |
get_user | Get a user by ID |
get_user_by_email | Get a user by email address |
get_current_user | Get the current authenticated user |
Statuses & Priorities
| Tool | Description |
|---|
get_statuses | Get all available test result statuses |
get_case_statuses | Get all available test case statuses (Enterprise) |
get_priorities | Get all available test case priorities |
Templates & Configurations
| Tool | Description |
|---|
get_templates | Get all templates for a project |
get_configs | Get all configurations for a project |
get_result_fields | Get all available result custom fields |
Attachments
| Tool | Description |
|---|
add_attachment_to_case | Add an attachment to a test case |
add_attachment_to_result | Add an attachment to a test result |
add_attachment_to_run | Add an attachment to a test run |
add_attachment_to_plan | Add an attachment to a test plan |
add_attachment_to_plan_entry | Add an attachment to a test plan entry |
get_attachment | Get/download an attachment by ID |
get_attachments_for_case | Get all attachments for a test case |
get_attachments_for_test | Get all attachments for a test |
get_attachments_for_run | Get all attachments for a test run |
get_attachments_for_plan | Get all attachments for a test plan |
get_attachments_for_plan_entry | Get all attachments for a test plan entry |
delete_attachment | Delete an attachment |
Usage Examples
Once configured, you can interact with TestRail through your AI assistant:
Get all projects
"List all TestRail projects"
Create a test case
"Create a new test case in section 123 with title 'Verify login functionality'"
Add test results
"Add a passed result for test case 456 in run 789 with comment 'All checks passed'"
Get test run results
"Show me all results for test run 101"
Test Result Status IDs
When adding results, use these standard status IDs:
| Status ID | Status |
|---|
| 1 | Passed |
| 2 | Blocked |
| 3 | Untested |
| 4 | Retest |
| 5 | Failed |
Development
Building from Source
git clone https://github.com/TenBarrel6/testrail-mcp.git
cd testrail-mcp
npm install
npm run build
npm run dev
Scripts
npm run build - Compile TypeScript to JavaScriptnpm run start - Run the compiled servernpm run dev - Run in development mode with hot reload
Requirements
- Node.js 18+
- TestRail instance with API access enabled
- Valid TestRail API key
Troubleshooting
"Not authenticated" Error
Ensure your environment variables are correctly set:
TESTRAIL_URL should include the protocol (https://)TESTRAIL_USERNAME should be your email addressTESTRAIL_API_KEY should be a valid API key (not your password)
Connection Issues
- Verify your TestRail URL is accessible
- Check if API access is enabled in your TestRail administration settings
- Ensure your user has appropriate permissions
MCP Client Not Connecting
- Restart your MCP client (Cursor/Claude Desktop)
- Verify the configuration JSON syntax is valid
- Check that
npx is available in your PATH
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature)
- Commit your changes (
git commit -m 'Add some amazing feature')
- Push to the branch (
git push origin feature/amazing-feature)
- Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Author
Ruslan Sapun
Links
