TestRail MCP ServerConnect AI assistants to TestRail

A free, open-source Model Context Protocol (MCP) server that lets Claude, Cursor, Windsurf, and VS Code manage TestRail test cases, runs, and results conversationally — plus a CLI for CI/CD.

Get Started

Browse all tools

View on GitHub

🔍 Discovery & Navigation

Browse TestRail projects, test suites, and sections so your AI assistant can map your QA organization before it writes anything.

Discovery tools

📋 Test Case Management

Fetch, create, update, and bulk-edit test cases, with schema validation against your instance's custom fields.

Case management tools

▶️ Execution & Tracking

Create test runs, submit results by test_id or case_id, and track pass/fail status straight from a chat message or a CI job.

Execution tools

🖥️ CLI & CI/CD Automation

Call any tool from bash, GitHub Actions, GitLab CI, or Jenkins with testrail-cli — deterministic exit codes, JSON on stdout, zero LLM cost.

CLI guide

📎 Attachments & Media

Attach screenshots, logs, or whole directories to cases, runs, and results. Directories are zipped automatically before upload.

Attachment tools

🧠 System Metadata

Expose statuses, priorities, templates, labels, and configurations so the model generates data that your TestRail instance actually accepts.

Metadata tools

🔗 Shared Steps

Create, update, and audit reusable shared test steps, with changes propagating to every linked test case.

Shared step tools

🔐 Least-Privilege Controls

Every tool declares a read, write, or delete mode. Deletes are off by default, and you can disable individual tools by name.

Configuration guide

What is the TestRail MCP Server?

The TestRail MCP Server is an open-source Model Context Protocol server that gives AI assistants direct, structured access to a TestRail instance through the TestRail API v2. Once it is configured, an assistant such as Claude Desktop, Cursor, Windsurf, or GitHub Copilot in VS Code can search test cases, draft new ones, start test runs, record results, and upload attachments on your behalf — without you leaving the chat window.

It is published on npm as @uarlouski/testrail-mcp-server, runs on Node.js 18 or newer over the MCP stdio transport, and is licensed under Apache 2.0. The server is tested against TestRail 10.6.2 (API v2) and stays backward compatible with older instances, including pre-7.x pagination.

Install it in one line

Point any MCP client at the package with npx and three environment variables:

json

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@uarlouski/testrail-mcp-server@latest"],
      "env": {
        "TESTRAIL_INSTANCE_URL": "https://your-instance.testrail.io",
        "TESTRAIL_USERNAME": "your@email.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

There is nothing to build, host, or deploy. Full per-client instructions are in the Getting Started guide.

Why use an MCP server for TestRail?

Maintaining test cases by hand is slow and error-prone: you copy requirements out of a ticket, retype them into TestRail's editor, guess at which custom fields are mandatory, and repeat it for every case. The TestRail MCP Server removes those steps.

No context switching. Stay in your IDE or chat client instead of tabbing into the TestRail web UI.
No copy-pasting. Ask for a set of cases, review them in chat, and push them to TestRail in the same breath.
Valid data on the first try. The server reads your instance's templates, priorities, statuses, and custom field definitions and validates payloads before they are sent, so the model cannot invent a field that does not exist.
The same tools in CI. Everything the AI can do, a shell script can do too — see the CLI guide.

Typical prompts that work out of the box:

"List all active projects in TestRail." · "Show me every test case in section 5 of project 3." · "Write a comprehensive test case for login validation with detailed steps and add it to the Authentication section." · "Start a test run with the cases from section 5 and assign it to me." · "Mark test case C1042 as passed with the comment 'verified on staging'."

What can it do?

The server exposes 34 MCP tools across seven areas:

Area	What your AI assistant can do	Tools
Discovery	Browse projects, suites, sections, and users	6 tools
Test cases	Read, create, update, bulk-edit, and export cases	9 tools
Execution	Create and update runs, read tests, submit results	6 tools
Attachments	Upload and download files, auto-zip directories	2 tools
Shared steps	Read, create, update, and audit shared steps	5 tools
Metadata	Statuses, priorities, fields, templates, labels, configs	6 tools
Deletion	Remove cases, shared steps, and attachments	1 tool

The complete tool reference lists every tool with its permission mode and the feature flag that enables it.

Is it safe to give an AI assistant access to TestRail?

That is the right question to ask, and the server is built around it. Access is layered rather than all-or-nothing:

Per-mode toggles. Every tool declares a read, write, or delete mode. Destructive delete tools are disabled unless you explicitly set TESTRAIL_ALLOW_DELETE_OPERATIONS=true.
Per-tool allowlisting. TESTRAIL_DISABLED_TOOLS removes named tools entirely, so you can permit add_results_for_cases while blocking mutate_suite.
Opt-in features. Shared steps, case history, and the experimental RAG export are off until you turn them on.
Your own credentials. The server runs locally and talks only to your TestRail instance using your API key. There is no third-party service in the middle.
MCP annotations. Read, write, and delete modes are surfaced to the client as readOnlyHint and destructiveHint, so clients that ask for confirmation can do so accurately.

Read the Configuration guide for the full permission matrix, or the FAQ for shorter answers.

Next steps

Getting Started — get a TestRail API key and configure your MCP client.
Configuration — every environment variable, permission, and feature flag.
Tool Reference — all 34 tools, grouped by what they do.
CLI & CI/CD — run TestRail operations from pipelines without an LLM.
FAQ — short answers to common setup and security questions.