Enables comprehensive interaction with TestRail's API for managing test projects, suites, cases, runs, plans, results, milestones, attachments, and user management. Supports full test lifecycle operations including creating/updating test cases, executing test runs, adding results, and managing test plans.
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 show me the test cases for project 123 in the regression suite"
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.
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.
🔐 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
Related MCP server: TestRail MCP Server
npm i -g @tenbarrel6/testrail-mcpnpm i @tenbarrel6/testrail-mcpNo installation required - run directly in downloaded github repository:
npx @tenbarrel6/testrail-mcpCreate 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-hereAdd 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"
}
}
}
}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"
}
}
}
}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
Tool | Description |
| Get all TestRail projects |
| Get a specific project by ID |
Tool | Description |
| Get all test suites for a project |
| Get a specific test suite by ID |
| Create a new test suite |
| Update an existing test suite |
Tool | Description |
| Get all sections for a project/suite |
| Get a specific section by ID |
| Create a new section |
| Update an existing section |
| Delete a section |
| Move a section to another parent or position |
Tool | Description |
| Get test cases for a project/suite |
| Get a specific test case by ID |
| Create a new test case |
| Update an existing test case |
| Delete a test case |
| Delete multiple test cases |
| Copy test cases to another section |
| Move test cases to another section |
| Get all available test case types |
| Get all available test case fields |
| Get the edit history for a test case |
Tool | Description |
| Get test runs for a project |
| Get a specific test run by ID |
| Create a new test run |
| Update an existing test run |
| Close a test run |
| Delete a test run |
Tool | Description |
| Get tests for a test run |
| Get a specific test by ID |
Tool | Description |
| Get results for a test |
| Get results for a test case in a run |
| Get all results for a test run |
| Add a test result |
| Add a test result for a specific case in a run |
| Add multiple test results by test IDs |
| Add multiple test results for cases in a run |
Tool | Description |
| Get test plans for a project |
| Get a specific test plan by ID |
| Create a new test plan |
| Update an existing test plan |
| Close a test plan |
| Delete a test plan |
| Add test runs to a test plan |
| Update a test plan entry |
| Delete a test plan entry |
| Add a test run to an existing plan entry |
| Update a test run inside a plan entry |
| Delete a test run from a plan entry |
Tool | Description |
| Get milestones for a project |
| Get a specific milestone by ID |
| Create a new milestone |
| Update an existing milestone |
| Delete a milestone |
Tool | Description |
| Get all users (optionally filtered by project) |
| Get a user by ID |
| Get a user by email address |
| Get the current authenticated user |
Tool | Description |
| Get all available test result statuses |
| Get all available test case statuses (Enterprise) |
| Get all available test case priorities |
Tool | Description |
| Get all templates for a project |
| Get all configurations for a project |
| Get all available result custom fields |
Tool | Description |
| Add an attachment to a test case |
| Add an attachment to a test result |
| Add an attachment to a test run |
| Add an attachment to a test plan |
| Add an attachment to a test plan entry |
| Get/download an attachment by ID |
| Get all attachments for a test case |
| Get all attachments for a test |
| Get all attachments for a test run |
| Get all attachments for a test plan |
| Get all attachments for a test plan entry |
| Delete an attachment |
Once configured, you can interact with TestRail through your AI assistant:
"List all TestRail projects""Create a new test case in section 123 with title 'Verify login functionality'""Add a passed result for test case 456 in run 789 with comment 'All checks passed'""Show me all results for test run 101"When adding results, use these standard status IDs:
Status ID | Status |
1 | Passed |
2 | Blocked |
3 | Untested |
4 | Retest |
5 | Failed |
# Clone the repository
git clone https://github.com/TenBarrel6/testrail-mcp.git
cd testrail-mcp
# Install dependencies
npm install
# Build
npm run build
# Run in development mode
npm run devnpm run build - Compile TypeScript to JavaScript
npm run start - Run the compiled server
npm run dev - Run in development mode with hot reload
Node.js 18+
TestRail instance with API access enabled
Valid TestRail API key
Ensure your environment variables are correctly set:
TESTRAIL_URL should include the protocol (https://)
TESTRAIL_USERNAME should be your email address
TESTRAIL_API_KEY should be a valid API key (not your password)
Verify your TestRail URL is accessible
Check if API access is enabled in your TestRail administration settings
Ensure your user has appropriate permissions
Restart your MCP client (Cursor/Claude Desktop)
Verify the configuration JSON syntax is valid
Check that npx is available in your PATH
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
This project is licensed under the MIT License - see the LICENSE file for details.
Ruslan Sapun
GitHub: @TenBarrel6
Add an attachment to a test case
Inputs: case_id (required), file_path (required).
Add an attachment to a test plan
Inputs: plan_id (required), file_path (required).
Add an attachment to a test plan entry
Inputs: plan_id (required), entry_id (required), file_path (required).
Add an attachment to a test result
Inputs: result_id (required), file_path (required).
Add an attachment to a test run
Inputs: run_id (required), file_path (required).
Create a new test case
Inputs: section_id (required), title (required), template_id, type_id, +9 more.
Create a new milestone
Inputs: project_id (required), name (required), description, due_on, +3 more.
Create a new test plan
Inputs: project_id (required), name (required), description, milestone_id, +1 more.
Add test runs to a test plan
Inputs: plan_id (required), suite_id (required), name, description, +6 more.
Add a test result
Inputs: test_id (required), status_id (required), comment, elapsed, +1 more.
Add a test result for a specific case in a run
Inputs: run_id (required), case_id (required), status_id (required), comment, +1 more.
Add multiple test results by test IDs
Inputs: run_id (required), results (required).
Add multiple test results for cases in a run
Inputs: run_id (required), results (required).
Create a new test run
Inputs: project_id (required), name (required), suite_id, description, +4 more.
Add a test run to an existing plan entry
Inputs: plan_id (required), entry_id (required), config_ids (required), description, +4 more.
Create a new section
Inputs: project_id (required), name (required), suite_id, parent_id, +1 more.
Create a new test suite
Inputs: project_id (required), name (required), description.
Close a test plan
Inputs: plan_id (required).
Close a test run
Inputs: run_id (required).
Copy test cases to another section
Inputs: section_id (required), case_ids (required).
Delete an attachment
Inputs: attachment_id (required).
Delete a test case
Inputs: case_id (required).
Delete multiple test cases
Inputs: project_id (required), case_ids (required), suite_id, soft.
Delete a milestone
Inputs: milestone_id (required).
Delete a test plan
Inputs: plan_id (required).
Delete a test plan entry
Inputs: plan_id (required), entry_id (required).
Delete a test run
Inputs: run_id (required), soft.
Delete a test run from a plan entry
Inputs: run_id (required).
Delete a section
Inputs: section_id (required).
Get/download an attachment by ID
Inputs: attachment_id (required).
Get all attachments for a test case
Inputs: case_id (required), limit, offset.
Get all attachments for a test plan
Inputs: plan_id (required), limit, offset.
Get all attachments for a test plan entry
Inputs: plan_id (required), entry_id (required).
Get all attachments for a test run
Inputs: run_id (required), limit, offset.
Get all attachments for a test
Inputs: test_id (required).
Get a specific test case by ID
Inputs: case_id (required).
Get all available test case fields
Inputs: no named parameters.
Get test cases for a project/suite
Inputs: project_id (required), suite_id, section_id.
Get all available test case statuses (Enterprise)
Inputs: no named parameters.
Get all available test case types
Inputs: no named parameters.
Get all configurations for a project
Inputs: project_id (required).
Get the current authenticated user
Inputs: no named parameters.
Get the edit history for a test case
Inputs: case_id (required), limit, offset.
Get a specific milestone by ID
Inputs: milestone_id (required).
Get milestones for a project
Inputs: project_id (required).
Get a specific test plan by ID
Inputs: plan_id (required).
Get test plans for a project
Inputs: project_id (required).
Get all available test case priorities
Inputs: no named parameters.
Get a specific project by ID
Inputs: project_id (required).
Get all TestRail projects
Inputs: no named parameters.
Get all available result custom fields
Inputs: no named parameters.
Get results for a test
Inputs: test_id (required).
Get results for a test case in a run
Inputs: run_id (required), case_id (required).
Get results for a test run
Inputs: run_id (required).
Get a specific test run by ID
Inputs: run_id (required).
Get test runs for a project
Inputs: project_id (required).
Get a specific section by ID
Inputs: section_id (required).
Get all sections for a project/suite
Inputs: project_id (required), suite_id.
Get all available test result statuses
Inputs: no named parameters.
Get a specific test suite by ID
Inputs: suite_id (required).
Get all test suites for a project
Inputs: project_id (required).
Get all templates for a project
Inputs: project_id (required).
Get a specific test by ID
Inputs: test_id (required).
Get tests for a test run
Inputs: run_id (required).
Get a user by ID
Inputs: user_id (required).
Get a user by email address
Inputs: email (required).
Get all users (optionally filtered by project)
Inputs: project_id.
Move test cases to another section
Inputs: section_id (required), suite_id (required), case_ids (required).
Move a section to another parent or position
Inputs: section_id (required), parent_id, after_id.
Update an existing test case
Inputs: case_id (required), title, template_id, type_id, +7 more.
Update an existing milestone
Inputs: milestone_id (required), name, description, due_on, +4 more.
Update an existing test plan
Inputs: plan_id (required), name, description, milestone_id.
Update a test plan entry
Inputs: plan_id (required), entry_id (required), name, description, +4 more.
Update an existing test run
Inputs: run_id (required), name, description, milestone_id.
Update a test run inside a plan entry
Inputs: run_id (required), description, assignedto_id, include_all, +2 more.
Update an existing section
Inputs: section_id (required), name, description.
Update an existing test suite
Inputs: suite_id (required), name, description.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 77 tools
Most tools have distinct purposes targeting specific resources and actions, but there is some overlap that could cause confusion. For example, 'add_result' and 'add_result_for_case' are similar, and multiple attachment tools for different resources might be misselected if the agent isn't careful about the target entity.
Tool names follow a highly consistent verb_noun pattern throughout, with clear actions like add, get, delete, update, copy, move, and close applied to specific nouns. This predictability makes it easy for agents to understand and navigate the toolset.
With 77 tools, the count is excessive for typical MCP server purposes, making it overwhelming and difficult to manage. This large number suggests over-fragmentation of operations that could have been consolidated, such as multiple attachment tools for different resources.
The toolset provides comprehensive CRUD and lifecycle coverage for TestRail's domain, including projects, suites, cases, runs, plans, results, attachments, and users. There are no obvious gaps, with tools for creation, retrieval, updates, deletions, and specialized operations like moving or copying cases.
Create and manage test cases, test runs and results in Testiny from your AI assistant.
Test management for AI agents: cases, runs, results, cycles and traceability.
Direct access to Cypress tests results and accessibility reports in your AI workflow.
Manage test suites, run tests, view results, and automate QA workflows via AI with testRigor.
