Testrail Mcp Server
About
AI-native MCP server connecting Claude, Cursor, Windsurf, and other AI assistants to TestRail — manage test cases, runs, and results through natural-language conversation, with typed schemas built for LLMs.
Explore
| Capability | Description |
|------------|-------------|
| 🔍 Intelligent Discovery | Browse projects, test suites, and sections to automatically map your QA organization. |
| 📋 Full Case Management | Fetch, create, update, and bulk-edit test cases with comprehensive custom field support. |
| ▶️ Actionable Execution | Create test runs, update results by test_id or case_id, attach files, and track statuses. |
| 🧠 Context-Aware AI | Dynamically exposes templates, fields, priorities, and statuses so LLMs generate valid, structured data. |
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Testrail Mcp ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Add the server to your chosen MCP client configuration. Below are examples for popular AI IDEs and assistants:
<details>
<summary><strong>🤖 Claude Desktop</strong></summary>
Add this to your claude_desktop_config.json:
``json`
{
"mcpServers": {
"testrail": {
"command": "npx",
"args": ["-y", "@uarlouski/testrail-mcp-server@latest"],
"env": {
"TESTRAIL_INSTANCE_URL": "https://your-instance.testrail.io",
"TESTRAIL_USERNAME": "[email protected]",
"TESTRAIL_API_KEY": "your-api-key"
}
}
}
}
</details>
<details>
<summary><strong>⌨️ Cursor</strong></summary>
Open Settings → Features → MCP and add a new configuration:
json`
{
"mcpServers": {
"testrail": {
"command": "npx",
"args": ["-y", "@uarlouski/testrail-mcp-server@latest"],
"env": {
"TESTRAIL_INSTANCE_URL": "https://your-instance.testrail.io",
"TESTRAIL_USERNAME": "[email protected]",
"TESTRAIL_API_KEY": "your-api-key"
}
}
}
}
</details>
<details>
<summary><strong>🌊 Windsurf</strong></summary>
Update your Windsurf MCP configuration file:
json`
{
"mcpServers": {
"testrail": {
"command": "npx",
"args": ["-y", "@uarlouski/testrail-mcp-server@latest"],
"env": {
"TESTRAIL_INSTANCE_URL": "https://your-instance.testrail.io",
"TESTRAIL_USERNAME": "[email protected]",
"TESTRAIL_API_KEY": "your-api-key"
}
}
}
}
</details>
<details>
<summary><strong>🌐 Other MCP Clients</strong></summary>
Any MCP-compliant client can utilize this server. The pattern is universal—point your client at the command with the required environment variables.
</details>
| Variable | Description | Required |
|----------|-------------|:--------:|
| TESTRAIL_INSTANCE_URL | Your TestRail instance URL (e.g., https://example.testrail.io) | ✅ |TESTRAIL_USERNAME
| | Your TestRail user email address | ✅ |TESTRAIL_API_KEY` | Your TestRail API key (Guide) | ✅ |
|
---
query_project
Retrieve a single project or all projects in TestRail. Set payload.action to 'one' or 'many' to specify the operation.
mutate_suite
Create a new test suite or update an existing one in TestRail. Set payload.action to 'create' or 'update' to specify the operation.
query_suite
Retrieve a single test suite or all test suites for a project in TestRail. Set payload.action to 'one' or 'many' to specify the operation.
get_case
Get detailed information about a test case including its custom fields
get_cases
Get all test cases for a project. Filter by section, API params (priority, type), or any field including custom fields via 'where'. Returns case IDs, titles, and any additional requested fields.
get_case_fields
Get the field schema for test cases for a specific project. You should normally provide project_id to get fields applicable to your project. If you truly need all fields across all projects, you may omit project_id, but this is rarely what you want. Returns available fields with their types and options (for dropdown fields).
update_case
Update a test case in TestRail. The update operation requires knowing valid field names that are returned by get_case_fields tool. Supports partial updates — only specify the fields you want to change.
update_cases
Bulk update multiple test cases with the same field values. The update operation requires knowing valid field names that are returned by get_case_fields tool. More efficient than calling update_case multiple times.
add_case
Create a new test case in TestRail. The create operation requires knowing valid field names that are returned by get_case_fields tool.
get_sections
Get all sections for a project. Returns section IDs and names that can be used with add_case
mutate_section
Create a new section or update an existing section in TestRail. Set payload.action to 'create' or 'update' to specify the operation.
mutate_run
Create a new test run or update an existing one in TestRail. Set payload.action to 'create' or 'update' to specify the operation.
query_run
Retrieve a single test run or all test runs for a project in TestRail. Set payload.action to 'one' or 'many' to specify the operation.
add_attachment_to_run
Add an attachment to a test run in TestRail. (Deprecated: Prefer add_attachment tool). Maximum upload size is 256MB.
add_results
Add one or more test results to a test run
add_results_for_cases
Add one or more test results to a test run using case IDs instead of test IDs
get_results
Get results for a specific test in TestRail.
add_attachment
Add an attachment to a test case or test run in TestRail. If the file_path points to a directory, it will be automatically zipped before uploading. Maximum upload size is 256MB.
query_attachment
Download a single attachment or list all attachments for a test case or test run in TestRail. Set payload.action to 'one' or 'many' to specify the operation.
get_configurations
Get all configuration groups and configurations for a project in TestRail.
get_labels
Get all available test case labels (sometimes called tags) for a project. Returns label IDs and titles that can be used when creating or updating test cases.
get_priorities
Get all available test case priorities (e.g. Critical, High, Medium, Low). Returns priority IDs and names that can be used when creating or updating test cases.
get_statuses
Get all available test statuses (e.g. Passed, Failed, Blocked). Returns status IDs and names that can be used with add_result and get_tests
get_templates
Get available test case templates for a project. Template IDs determine which fields are available when creating or updating test cases
get_tests
Get tests for a test run, optionally filtered by status
get_users
Get active users from TestRail. Resolves active users globally or per-project. If global fetch is forbidden (for non-admin accounts), falls back to merging users across all active projects so users referenced as reviewers or assignees can be resolved.
The TestRail MCP Server provides heavily typed, descriptive tools designed specifically for LLM interaction:
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"testrail mcp server": {
"testrail": {
"command": "npx",
"args": [
"-y",
"@uarlouski/testrail-mcp-server@latest"
],
"env": {
"TESTRAIL_INSTANCE_URL": "https://your-instance.testrail.io",
"TESTRAIL_USERNAME": "[email protected]",
"TESTRAIL_API_KEY": "your-api-key"
}
}
}
}
}McpServers
{
"testrail": {
"command": "npx",
"args": [
"-y",
"@uarlouski/testrail-mcp-server@latest"
],
"env": {
"TESTRAIL_INSTANCE_URL": "https://your-instance.testrail.io",
"TESTRAIL_USERNAME": "[email protected]",
"TESTRAIL_API_KEY": "your-api-key"
}
}
}🌟 Why Choose TestRail MCP Server?
Managing test cases manually is tedious and error-prone. With the TestRail MCP Server, your AI assistant (whether it’s Claude, Cursor, Windsurf, or any MCP-compliant client) interacts directly with your TestRail instance. Instruct it to find test cases, draft new ones, kick off test runs, and record test results—all through natural conversation. No context switching. No tedious copy-pasting. Just ask your AI.Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
