testrail-mcp-server — Claude Code MCP server for TestRail cases
Wires your AI assistant into TestRail so it can look up and draft test cases, start runs, log results and upload attachments without leaving the chat.
claude mcp add --env TESTRAIL_INSTANCE_URL=<TESTRAIL_INSTANCE_URL> --env TESTRAIL_USERNAME=<TESTRAIL_USERNAME> --env TESTRAIL_API_KEY=<TESTRAIL_API_KEY> --env TESTRAIL_ENABLE_SHARED_STEPS=<TESTRAIL_ENABLE_SHARED_STEPS> --env TESTRAIL_ENABLE_CASE_HISTORY=<TESTRAIL_ENABLE_CASE_HISTORY> --transport stdio testrail-mcp-server -- npx -y @uarlouski/testrail-mcp-serverWhat testrail-mcp-server does
The server talks to your TestRail instance over API v2. It ships 35 tools covering projects, suites and sections, test case work with custom fields, run creation, result updates keyed by test_id or case_id, and file attachments. Templates, fields, priorities and statuses are surfaced to the model, so what it writes back stays valid.
It runs on your machine with Node.js 18+ and speaks the stdio transport; your client starts it through npx, so there is no host to maintain. A separate testrail-cli exposes the same operations for bash scripts, GitHub Actions, GitLab CI or Jenkins when you want no model in the loop.
You need an API key from TestRail (My Settings → API Keys) and the API switched on for the whole instance (Administration → Site Settings → API). Permissions work per mode and per tool, and deletes stay off until you turn them on — leave that flag alone and the assistant cannot remove anything. Tested against TestRail 10.6.2; older instances, including pagination from before 7.x, still work, as do cloud and self-hosted deployments.
What it helps with
- pull up a test case by name without opening the TestRail UI
- draft a batch of cases from a feature description
- kick off a run and set statuses from test output
- attach a screenshot or log to a result
- replay the same operations from CI with no model involved
Example prompts for the agent
- Find every test case in the Checkout project about returns
- Create a case for retrying a failed payment and add it to the Payments suite
- Start a run on the Smoke suite and mark the failing tests
How to install testrail-mcp-server
Platform CLI
claude mcp add --env TESTRAIL_INSTANCE_URL=<TESTRAIL_INSTANCE_URL> --env TESTRAIL_USERNAME=<TESTRAIL_USERNAME> --env TESTRAIL_API_KEY=<TESTRAIL_API_KEY> --env TESTRAIL_ENABLE_SHARED_STEPS=<TESTRAIL_ENABLE_SHARED_STEPS> --env TESTRAIL_ENABLE_CASE_HISTORY=<TESTRAIL_ENABLE_CASE_HISTORY> --transport stdio testrail-mcp-server -- npx -y @uarlouski/testrail-mcp-serverReplace <…> with your own values. 7 more environment variables are in the server README
Platform CLI
codex mcp add testrail-mcp-server --env TESTRAIL_INSTANCE_URL=<TESTRAIL_INSTANCE_URL> --env TESTRAIL_USERNAME=<TESTRAIL_USERNAME> --env TESTRAIL_API_KEY=<TESTRAIL_API_KEY> --env TESTRAIL_ENABLE_SHARED_STEPS=<TESTRAIL_ENABLE_SHARED_STEPS> --env TESTRAIL_ENABLE_CASE_HISTORY=<TESTRAIL_ENABLE_CASE_HISTORY> -- npx -y @uarlouski/testrail-mcp-serverReplace <…> with your own values. 7 more environment variables are in the server README
Config file
{
"mcpServers": {
"testrail-mcp-server": {
"command": "npx",
"args": [
"-y",
"@uarlouski/testrail-mcp-server"
],
"env": {
"TESTRAIL_INSTANCE_URL": "<TESTRAIL_INSTANCE_URL>",
"TESTRAIL_USERNAME": "<TESTRAIL_USERNAME>",
"TESTRAIL_API_KEY": "<TESTRAIL_API_KEY>",
"TESTRAIL_ENABLE_SHARED_STEPS": "<TESTRAIL_ENABLE_SHARED_STEPS>",
"TESTRAIL_ENABLE_CASE_HISTORY": "<TESTRAIL_ENABLE_CASE_HISTORY>"
}
}
}
}Replace <…> with your own values. 7 more environment variables are in the server README
Config file
{
"servers": {
"testrail-mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@uarlouski/testrail-mcp-server"
],
"env": {
"TESTRAIL_INSTANCE_URL": "<TESTRAIL_INSTANCE_URL>",
"TESTRAIL_USERNAME": "<TESTRAIL_USERNAME>",
"TESTRAIL_API_KEY": "<TESTRAIL_API_KEY>",
"TESTRAIL_ENABLE_SHARED_STEPS": "<TESTRAIL_ENABLE_SHARED_STEPS>",
"TESTRAIL_ENABLE_CASE_HISTORY": "<TESTRAIL_ENABLE_CASE_HISTORY>"
}
}
}
}Replace <…> with your own values. 7 more environment variables are in the server README
Platform CLI
gemini mcp add -e TESTRAIL_INSTANCE_URL=<TESTRAIL_INSTANCE_URL> -e TESTRAIL_USERNAME=<TESTRAIL_USERNAME> -e TESTRAIL_API_KEY=<TESTRAIL_API_KEY> -e TESTRAIL_ENABLE_SHARED_STEPS=<TESTRAIL_ENABLE_SHARED_STEPS> -e TESTRAIL_ENABLE_CASE_HISTORY=<TESTRAIL_ENABLE_CASE_HISTORY> testrail-mcp-server npx -y @uarlouski/testrail-mcp-serverReplace <…> with your own values. 7 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about testrail-mcp-server
How do I install testrail-mcp-server in Claude Code?
Run `claude mcp add testrail-mcp-server -e TESTRAIL_INSTANCE_URL=<TESTRAIL_INSTANCE_URL> -e TESTRAIL_USERNAME=<TESTRAIL_USERNAME> -e TESTRAIL_API_KEY=<TESTRAIL_API_KEY> -- npx -y @uarlouski/testrail-mcp-server`. Fill in your instance URL, username and API key.
What does testrail-mcp-server do?
It gives an AI assistant structured access to TestRail through API v2: searching and creating cases, runs, results and attachments. 35 tools in total, all running locally.
What do I need before connecting it?
An API key from My Settings → API Keys, plus the API enabled instance-wide under Administration → Site Settings → API. Without both, the server cannot authenticate.
