TestRail MCP Server
Provides comprehensive TestRail API integration for managing test cases, projects, suites, runs, and tests. Enables updating test cases and runs, adding test results and attachments, and retrieving test data with filtering capabilities.
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 5 that failed in the last run"
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
What is this?
This tool connects your TestRail test management system with AI assistants like Cursor or Claude Desktop. It allows your AI assistant to read and update test cases, add test results, and manage your testing workflow through simple conversations.
Related MCP server: TestRail MCP Server
Features
View Test Cases: Show test cases, projects, and test runs
Update Tests: Modify test case details, titles, and descriptions
Add Results: Record test results and upload screenshots
Search & Filter: Find specific tests or projects quickly
File Attachments: Upload documents and images to test cases
Full Integration: Works with Cursor, Claude Desktop, and other AI tools
Who is this for?
QA Engineers who want to manage tests through AI conversations
Project Managers who need quick access to test information
Developers who want to integrate testing into their AI-assisted workflow
Anyone who uses TestRail and wants to make it more accessible through AI
Quick Start
Install Node.js from nodejs.org
Get TestRail API key from your TestRail settings
Install the server:
npm install -g testrail-mcp-serverConfigure your AI assistant with your TestRail credentials
Restart your AI assistant and start asking questions!
Prerequisites
You need these tools before installing:
Node.js 18.17.0+ - Download from nodejs.org (LTS version)
npm - Comes with Node.js automatically
AI Assistant - Cursor (cursor.sh) or Claude Desktop (claude.ai)
TestRail Account - With API access enabled
Verify installation:
node --version # Should show 18.17.0 or higher
npm --version # Should show a version numberGetting TestRail API Credentials
Log into TestRail at your instance URL (e.g.,
https://yourcompany.testrail.com)Get API Key:
Click your profile picture → "My Settings"
Scroll to "API Keys" section
Click "Add API Key"
Name it (e.g., "MCP Server")
Copy and save the API key securely
Note your credentials:
Username: Your TestRail login (usually email)
URL: Your TestRail web address
Installation
Step 1: Install the Server
Open Command Prompt/Terminal and run:
npm install -g testrail-mcp-serverStep 2: Configure Your AI Assistant
For Cursor Users:
Open Cursor → Settings (
Ctrl + ,orCmd + ,)Find "MCP" settings
Add this configuration:
{
"mcpServers": {
"testrail": {
"command": "npx",
"args": ["testrail-mcp-server"],
"env": {
"TESTRAIL_USERNAME": "your_testrail_username",
"TESTRAIL_API_KEY": "your_testrail_api_key",
"TESTRAIL_URL": "https://your-instance.testrail.com"
}
}
}
}For Claude Desktop Users:
Find config file:
Windows:
%APPDATA%\Claude\claude_desktop_config.jsonMac:
~/Library/Application Support/Claude/claude_desktop_config.json
Add the same configuration as above
Replace these values:
your_testrail_username: Your TestRail login (usually email)your_testrail_api_key: The API key from TestRailhttps://your-instance.testrail.com: Your TestRail URL
Step 3: Restart and Test
Restart your AI assistant completely
Test: Ask "Can you show me my TestRail projects?"
Usage
Once set up, simply talk to your AI assistant naturally:
Viewing Information:
"Show me all my TestRail projects"
"What test cases are in project 1?"
"Show me test case number 123"
Updating Tests:
"Update test case 123 with the title 'Login functionality test'"
"Change the priority of test case 456 to high"
"Add a comment to test case 789"
Adding Results:
"Mark test 456 as passed"
"Add a failed result to test 789 with comment 'Button not clickable'"
"Upload this screenshot to test case 123"
Searching:
"Find all test cases with 'login' in the title"
"Show me failed tests from the last test run"
Troubleshooting
"Command not found" or "npm is not recognized"
Install Node.js from nodejs.org
Restart Command Prompt/Terminal
Check with
node --version
"Authentication failed" or "Invalid credentials"
Verify your TestRail username (usually email)
Copy API key again from TestRail
Check TestRail URL starts with
https://
"Connection timeout" or "Cannot connect to TestRail"
Check internet connection
Verify TestRail URL is correct
Test TestRail in web browser
AI assistant doesn't respond to TestRail questions
Restart your AI assistant completely
Check configuration file format (valid JSON)
Verify all required fields are filled
"Permission denied" error
Run Command Prompt as Administrator (Windows) or with
sudo(Mac/Linux)Update to latest Node.js version
Still having trouble?
Check error messages for clues
Try installation steps again
Create an issue on GitHub with your error details
Security Best Practices
Never share your API key - treat it like a password
Use HTTPS URLs - ensure your TestRail URL starts with
https://Don't put API keys in code - always use configuration files
Rotate API keys regularly - change them every few months
Keep TestRail account secure - use strong passwords and 2FA
What NOT to do:
Don't share configuration files with others
Don't put API keys in public repositories
Don't use HTTP URLs (only HTTPS)
Don't share screenshots showing your API key
Additional Resources
Helpful Links:
Getting Support:
GitHub Issues - Report bugs or ask questions
Contact your TestRail administrator for API access issues
License
MIT License - see LICENSE file for details.
Available Tools
18 toolsadd_attachment_to_caseAdd Attachment to TestRail CaseC
Upload a file attachment to a TestRail test case.
Inputs: case_id (required), file_path (required).
add_caseAdd TestRail CaseA
Create a new TestRail test case in a specific section. IMPORTANT: Before creating a case, gather required information using get_projects, get_suites, get_sections, and get_case_fields tools to ensure proper section_id, type_id, and custom field values. Or ask the user to provide the information if not provided.
Inputs: title (required), section_id (required), type_id, priority_id, +2 more.
add_resultAdd TestRail ResultC
Adds a new test result, comment, or assigns a test.
Inputs: test_id (required), status_id (required), comment, version, +5 more.
get_caseGet TestRail CaseC
Fetch a TestRail test case by ID.
Inputs: case_id (required).
get_case_fieldsGet TestRail Case FieldsB
Returns a list of available test case custom fields.
Inputs: no named parameters.
get_casesGet TestRail CasesB
Get a list of test cases for a project or specific test suite with optional filtering and pagination.
Inputs: project_id (required), suite_id, created_after, created_before, +14 more.
get_projectGet TestRail ProjectB
Get details for a specific TestRail project by ID.
Inputs: project_id (required).
get_projectsGet TestRail ProjectsB
List all TestRail projects.
Inputs: no named parameters.
get_runGet TestRail RunB
Returns an existing test run. Please see get tests for the list of included tests in this run.
Inputs: run_id (required).
get_runsGet TestRail RunsA
Get a list of test runs for a project with optional filtering and pagination. Only returns test runs that are not part of a test plan.
Inputs: project_id (required), created_after, created_before, created_by, +6 more.
get_sectionsGet TestRail SectionsC
Get a list of sections for a project and test suite with optional pagination.
Inputs: project_id (required), suite_id, limit, offset.
get_suiteGet TestRail SuiteC
Get details for a specific TestRail test suite by ID.
Inputs: suite_id (required).
get_suitesGet TestRail SuitesB
Get all test suites for a specific TestRail project by ID.
Inputs: project_id (required).
get_testGet TestRail TestC
Returns an existing test.
Inputs: test_id (required), with_data.
get_testsGet TestRail TestsC
Returns a list of tests for a test run.
Inputs: run_id (required), status_id, limit, offset, +1 more.
update_caseUpdate TestRail CaseC
Update a TestRail test case by ID with new field values.
Inputs: case_id (required), title, section_id, type_id, +3 more.
update_runUpdate TestRail RunC
Updates an existing test run. Partial updates are supported.
Inputs: run_id (required), name, description, milestone_id, +8 more.
update_testUpdate TestRail TestC
Updates the labels assigned to an existing test.
Inputs: test_id (required), labels, custom.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Most tools have distinct purposes targeting specific TestRail resources (cases, runs, tests, projects, suites, sections, fields), but there is some overlap between get_case/get_cases and get_test/get_tests that could cause confusion if an agent misinterprets singular vs. plural usage. The descriptions help clarify, but the naming similarity creates minor ambiguity.
All tool names follow a consistent verb_noun pattern with snake_case, using clear action verbs like get, add, and update paired with specific nouns (e.g., get_case, add_attachment_to_case, update_run). This uniformity makes the tool set predictable and easy to navigate.
With 18 tools, the count is slightly high but reasonable for a comprehensive TestRail API coverage, including CRUD operations for cases, runs, tests, and supporting resources like projects and suites. It feels slightly heavy but well-scoped to the domain without being excessive.
The tool set provides complete CRUD/lifecycle coverage for TestRail's core domain, including projects, suites, sections, cases, runs, tests, and attachments. It supports creation (add_case), retrieval (get_* tools), updates (update_* tools), and result management (add_result), with no obvious gaps for essential workflows.
Maintenance
Related MCP Connectors
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.
Manage test suites, run tests, view results, and automate QA workflows via AI with testRigor.
Direct access to Cypress tests results and accessibility reports in your AI workflow.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to interact directly with TestRail instances for managing test projects, suites, cases, runs, results, plans, milestones, and attachments through the TestRail API with secure authentication.7755 npm1MIT
- 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
- AlicenseBqualityDmaintenanceEnables AI assistants to interact with TestRail test management system, supporting full CRUD operations on projects, suites, sections, test cases, runs, results, plans, and milestones.35327 npm1MIT
- AlicenseBqualityDmaintenanceEnables management of TestRail projects, suites, test cases, runs, and results through natural language.42MIT