query_projectLABSCO SUMMARY
It hands the model TestRail's own field definitions, which is why the cases it writes are valid.
Anyone who has scripted against TestRail knows the failure mode: a case that looks right and is rejected because a custom field wants an ID, not a label. Exposing templates, fields, statuses, priorities and configurations as tools — with resolve_case_field to translate a name — moves that problem out of the prompt and into data. Two switches worth setting deliberately: writes are on by default and can be turned off entirely, and shared steps and case history stay unregistered unless you enable them, which keeps the tool surface smaller.
What it is
A TypeScript server covering the TestRail API: projects and suites, test cases with custom fields, runs and results, attachments, and the metadata a model needs to produce valid records.
What you get
- Discovery: query_project, query_suite, get_sections and mutate_suite or mutate_section for structure changes
- Cases: get_case, get_cases, add_case, update_case and update_cases for bulk edits
- Execution: query_run and mutate_run for runs, get_tests for what is in one, and get_results, add_results and add_results_for_cases for outcomes
- Metadata exposed to the model so it generates valid data: get_case_fields, get_templates, get_statuses, get_priorities, get_configurations and get_users
- resolve_case_field — a field name turned into the identifier TestRail expects
- Attachments: add_attachment, add_attachment_to_run and query_attachment for pulling one back
- Optional shared steps management — get_shared_steps, add_shared_step, update_shared_step and their history
- Optional case history, so you can see what changed after a given revision or timestamp
- delete_entity for removals, kept as a separate explicit tool
Requirements
Three values from your TestRail instance: TESTRAIL_INSTANCE_URL, TESTRAIL_USERNAME and an API key from My Settings → API Keys in TESTRAIL_API_KEY. Run with npx from @uarlouski/testrail-mcp-server. Writes can be switched off with TESTRAIL_ALLOW_WRITE_OPERATIONS, and shared steps and case history are opt-in through their own flags. Validated against TestRail 10.6.2 on API v2, with backward compatibility for older instances.
Setup effort
One command plus a key — npx -y @uarlouski/testrail-mcp-server@latest, then supply credentials
USE CASES
01
Writing test cases from a requirement instead of by hand
The model reads the templates and field definitions first, then creates cases that TestRail accepts.
02
Finding your way around an instance you did not set up
Browse projects, suites and sections to map how the QA organisation is arranged before touching anything.
03
Recording a run's outcome as you go
Create the run, then post results by test or by case as each one finishes.
04
Attaching the evidence for a failure
Upload the log or screenshot to the result or the run, in the same conversation where you found it.
05
Letting an assistant read TestRail without changing it
Turn write operations off, and browsing, searching and reporting keep working while nothing can be modified.
06
Fixing a field across many cases at once
Bulk-update the cases rather than editing them one at a time in the UI.
33 tools
Listed in project docs. Your client may show a different list.
query_suitemutate_suitemutate_sectionget_sectionsget_usersget_casesget_caseget_case_historyadd_caseupdate_caseupdate_casesresolve_case_fieldquery_runmutate_runget_testsget_resultsadd_resultsadd_results_for_casesadd_attachmentquery_attachmentget_statusesget_prioritiesget_case_fieldsget_templatesget_configurationsget_shared_stepsget_shared_stepget_shared_step_historyadd_shared_stepupdate_shared_stepdelete_entityadd_attachment_to_runBEFORE YOU INSTALL
What to know first
Tools you get
33 tools named in the project's documentation.
Requires
- npx on PATH
- TESTRAIL_INSTANCE_URL in your environment
- TESTRAIL_API_KEY in your environment
- TESTRAIL_USERNAME in your environment
INSTALLATION
Connect your client
Server setup
TERMINAL
npx -y @uarlouski/testrail-mcp-server@latestMCP Clients
Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"testrail": {
"command": "npx",
"args": [
"-y",
"@uarlouski/testrail-mcp-server@latest"
],
"env": {
"TESTRAIL_INSTANCE_URL": "https://<YOUR_INSTANCE>.testrail.io",
"TESTRAIL_USERNAME": "<YOUR_TESTRAIL_USERNAME>",
"TESTRAIL_API_KEY": "<YOUR_TESTRAIL_API_KEY>",
"TESTRAIL_ENABLE_SHARED_STEPS": "true"
}
}
}
}Cursor, Windsurf, Any MCP client
JSON
{
"mcpServers": {
"testrail": {
"command": "npx",
"args": [
"-y",
"@uarlouski/testrail-mcp-server@latest"
],
"env": {
"TESTRAIL_INSTANCE_URL": "https://<YOUR_INSTANCE>.testrail.io",
"TESTRAIL_USERNAME": "<YOUR_TESTRAIL_USERNAME>",
"TESTRAIL_API_KEY": "<YOUR_TESTRAIL_API_KEY>"
}
}
}
}
