# testrail-mcp-server 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. - MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 44 - Author: uarlouski - License: Apache-2.0 · policy=link-only · description only; the file stays with the author - Source: https://github.com/uarlouski/testrail-mcp-server - Updated: 2026-10-23 - HTML: https://affpapa.org/en/nevibecode/mcp/testrail-mcp-server ## What it 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. ## Requirements - Needs: Node.js (commands run via npx) - Environment variables: `TESTRAIL_INSTANCE_URL`, `TESTRAIL_USERNAME`, `TESTRAIL_API_KEY`, `TESTRAIL_ENABLE_SHARED_STEPS`, `TESTRAIL_ENABLE_CASE_HISTORY`, `TESTRAIL_ENABLE_RAG_TOOLS`, `TESTRAIL_ALLOW_WRITE_OPERATIONS`, `TESTRAIL_ALLOW_READ_OPERATIONS`, `TESTRAIL_ALLOW_DELETE_OPERATIONS`, `TESTRAIL_ENABLE_DEPRECATED_TOOLS` — keys and tokens: ask the human for the values, never commit them or put them in shared files. ## Install ### Claude Code (native platform) **Platform CLI** ```bash claude mcp add --env TESTRAIL_INSTANCE_URL= --env TESTRAIL_USERNAME= --env TESTRAIL_API_KEY= --env TESTRAIL_ENABLE_SHARED_STEPS= --env TESTRAIL_ENABLE_CASE_HISTORY= --transport stdio testrail-mcp-server -- npx -y @uarlouski/testrail-mcp-server ``` Replace <…> with your own values. 7 more environment variables are in the server README ### Codex **Platform CLI** ```bash codex mcp add testrail-mcp-server --env TESTRAIL_INSTANCE_URL= --env TESTRAIL_USERNAME= --env TESTRAIL_API_KEY= --env TESTRAIL_ENABLE_SHARED_STEPS= --env TESTRAIL_ENABLE_CASE_HISTORY= -- npx -y @uarlouski/testrail-mcp-server ``` Replace <…> with your own values. 7 more environment variables are in the server README ### Cursor **Config file** File `.cursor/mcp.json`: ```json { "mcpServers": { "testrail-mcp-server": { "command": "npx", "args": [ "-y", "@uarlouski/testrail-mcp-server" ], "env": { "TESTRAIL_INSTANCE_URL": "", "TESTRAIL_USERNAME": "", "TESTRAIL_API_KEY": "", "TESTRAIL_ENABLE_SHARED_STEPS": "", "TESTRAIL_ENABLE_CASE_HISTORY": "" } } } } ``` Replace <…> with your own values. 7 more environment variables are in the server README ### GitHub Copilot **Config file** File `.vscode/mcp.json`: ```json { "servers": { "testrail-mcp-server": { "type": "stdio", "command": "npx", "args": [ "-y", "@uarlouski/testrail-mcp-server" ], "env": { "TESTRAIL_INSTANCE_URL": "", "TESTRAIL_USERNAME": "", "TESTRAIL_API_KEY": "", "TESTRAIL_ENABLE_SHARED_STEPS": "", "TESTRAIL_ENABLE_CASE_HISTORY": "" } } } } ``` Replace <…> with your own values. 7 more environment variables are in the server README ### Gemini CLI **Platform CLI** ```bash gemini mcp add -e TESTRAIL_INSTANCE_URL= -e TESTRAIL_USERNAME= -e TESTRAIL_API_KEY= -e TESTRAIL_ENABLE_SHARED_STEPS= -e TESTRAIL_ENABLE_CASE_HISTORY= testrail-mcp-server npx -y @uarlouski/testrail-mcp-server ``` Replace <…> with your own values. 7 more environment variables are in the server README ## When to use it - 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 - 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 ## Similar - [Front-End Checklist](https://affpapa.org/en/nevibecode/mcp/front-end-checklist.md) — MCP server · ★ 74559 - [Keploy](https://affpapa.org/en/nevibecode/mcp/keploy.md) — MCP server · ★ 18727 - [SeleniumBase MCP](https://affpapa.org/en/nevibecode/mcp/seleniumbase-mcp.md) — MCP server · ★ 13169 - [mobile-mcp](https://affpapa.org/en/nevibecode/mcp/mobile-mcp.md) — MCP server · ★ 9946 - [e2e](https://affpapa.org/en/nevibecode/mcp/e2e.md) — MCP server · ★ 11912 - [mockserver](https://affpapa.org/en/nevibecode/mcp/mockserver.md) — MCP server · ★ 4996 --- NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md