testrail-mcp-server

<div align="center">
  <h1>🚀 TestRail MCP Server</h1>
  <p>
    <strong>An open-source Model Context Protocol (MCP) server that connects Claude, Cursor, Windsurf, and other AI assistants directly to TestRail.</strong>
  </p>
  <p>
    Manage TestRail projects, search and create test cases, kick off test runs, record results, and attach files — all through natural-language conversation with your AI assistant. Built for QA engineers and AI-assisted test automation.
  </p>
</div>

<p align="center">
  <a href="https://www.npmjs.com/package/@uarlouski/testrail-mcp-server"><img src="https://badge.fury.io/js/@uarlouski%2Ftestrail-mcp-server.svg" alt="npm version"></a>
  <a href="https://www.npmjs.com/package/@uarlouski/testrail-mcp-server"><img src="https://img.shields.io/npm/dm/@uarlouski/testrail-mcp-server.svg" alt="npm downloads"></a>
  <a href="https://github.com/uarlouski/testrail-mcp-server/actions/workflows/ci.yml"><img src="https://github.com/uarlouski/testrail-mcp-server/actions/workflows/ci.yml/badge.svg" alt="CI Status"></a>
  <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License"></a>
  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.9-blue.svg" alt="TypeScript"></a>
  <a href="https://github.com/uarlouski/testrail-mcp-server"><img src="https://img.shields.io/github/stars/uarlouski/testrail-mcp-server.svg?style=social&label=Star" alt="GitHub stars"></a>
  <a href="https://glama.ai/mcp/servers/uarlouski/testrail-mcp-server"><img src="https://glama.ai/mcp/servers/uarlouski/testrail-mcp-server/badges/score.svg" alt="Score Badge"></a>
</p>

<p align="center">
  <strong>Compatible with:</strong>
  <img src="https://img.shields.io/badge/Claude%20Desktop-D97757?logo=anthropic&logoColor=white" alt="Claude Desktop">
  <img src="https://img.shields.io/badge/Cursor-000000?logo=cursor&logoColor=white" alt="Cursor">
  <img src="https://img.shields.io/badge/Windsurf-19A1BC?logo=codeium&logoColor=white" alt="Windsurf">
  <img src="https://img.shields.io/badge/VS%20Code-007ACC?logo=visualstudiocode&logoColor=white" alt="VS Code">
</p>

<!-- TODO: insert demo.gif — short screencast of asking "create a test case" in Claude or Cursor and seeing the case appear in TestRail -->

---

## 🌟 Why Choose TestRail MCP Server?

Managing test cases manually is tedious and error-prone. With the **TestRail MCP Server**, your AI assistant (whether it’s **Claude, Cursor, Windsurf**, or any MCP-compliant client) interacts directly with your TestRail instance. Instruct it to find test cases, draft new ones, kick off test runs, and record test results—all through natural conversation.

**No context switching. No tedious copy-pasting. Just ask your AI.**

## ✨ Key Features & Capabilities

| Capability | Description |
|------------|-------------|
| **🔍 Intelligent Discovery** | Browse projects, test suites, and sections to automatically map your QA organization. |
| **📋 Full Case Management** | Fetch, create, update, and bulk-edit test cases with comprehensive custom field support. |
| **▶️ Actionable Execution** | Create test runs, update results by `test_id` or `case_id`, attach files, and track statuses. |
| **🧠 Context-Aware AI** | Dynamically exposes templates, fields, priorities, and statuses so LLMs generate valid, structured data. |

## 🚀 Quick Start Guide

### 1. Obtain Your TestRail API Key

Navigate to **My Settings → API Keys** in your TestRail platform and generate a new key for authentication.

### 2. Configure Your MCP Client

Add the server to your chosen MCP client configuration. The Claude Desktop example is shown below; Cursor, Windsurf, and other clients use the same pattern (see the collapsible sections further down).

#### 🤖 Claude Desktop

Add this to your `claude_desktop_config.json`:

```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",
        "TESTRAIL_ENABLE_SHARED_STEPS": "true"
      }
    }
  }
}
```

<details>
<summary><strong>⌨️ Cursor</strong></summary>

Open **Settings → Features → MCP** and add a new configuration:

```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"
      }
    }
  }
}
```
</details>

<details>
<summary><strong>🌊 Windsurf</strong></summary>

Update your Windsurf MCP configuration file:

```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"
      }
    }
  }
}
```
</details>

<details>
<summary><strong>🌐 Other MCP Clients</strong></summary>

Any MCP-compliant client can utilize this server. The pattern is universal—point your client at the `npx` command with the required environment variables.
</details>

### 3. See It in Action

Once configured, turbo-charge your QA workflow by asking your AI assistant:

- *"List all projects in TestRail to find the latest active project."*
- *"Show me all active users in the project to find the right assignee."*
- *"Show me all test cases in section 5 of project 3."*
- *"Create a comprehensive test case for 'Login Validation' with detailed steps."*
- *"Start a new test run containing cases from section 5."*
- *"Mark test case ID 1042 as passed with the comment 'Tested successfully on staging'."*

---

## ⚙️ Environment Variables & Security Controls

| Variable | Description | Required | Default |
|----------|-------------|:--------:|:-------:|
| `TESTRAIL_INSTANCE_URL` | Your TestRail instance URL (e.g., `https://example.testrail.io`) | ✅ | |
| `TESTRAIL_USERNAME` | Your TestRail user email address | ✅ | |
| `TESTRAIL_API_KEY` | Your TestRail API key ([Guide](https://support.testrail.com/hc/en-us/articles/7077039051412-Accessing-the-TestRail-API)) | ✅ | |
| `TESTRAIL_ENABLE_SHARED_STEPS` | Set to `true` to enable Shared Steps management tools | | `false` |
| `TESTRAIL_ALLOW_WRITE_OPERATIONS` | Allow write operations (e.g. adding/updating test cases, test runs, sections) | | `true` |
| `TESTRAIL_ALLOW_READ_OPERATIONS` | Allow read operations (e.g. retrieving projects, test cases, templates) | | `true` |
| `TESTRAIL_ALLOW_DELETE_OPERATIONS` | Allow delete operations (e.g. deleting cases or shared steps). Enabled strictly via `true`. | | `false` |

---

## 🛠️ Complete Tool Reference

The TestRail MCP Server provides heavily typed, descriptive tools designed specifically for LLM interaction:

> **💡 Pro Tip: Handling Large Data Sets & Permissions**
> - **Large Data Sets**: For list-based tools like `get_cases` and `get_sections`, you can supply the `output_file` parameter with an absolute file path. The server will bypass the LLM context window by writing the raw JSON directly to disk and returning a concise summary, allowing you to run external scripts against the export!
> - **Intelligent User Fallback**: When fetching users using `get_users` without admin rights, TestRail denies access globally. The server dynamically catches this permission restriction and falls back to polling all active projects in parallel, retrieving and deduplicating active users so assignees and reviewers can always be mapped.

### 🔭 Discovery & Navigation
| Tool | Functionality |
|------|-------------|
| `query_project` | Retrieve a single project (`action: "one"`) or all active projects (`action: "many"`). |
| `query_suite` | Retrieve a single test suite (`action: "one"`) or all test suites for a project (`action: "many"`). |
| `get_sections` | Navigate the precise folder/section hierarchy of any test suite. |
| `mutate_suite` | Create a new test suite or update an existing one in TestRail. |
| `mutate_section` | Create a new section or update an existing section in TestRail. |
| `get_users` | Retrieve active users. Handles per-project filtering and automatic fallback polling for non-admin accounts. |

### 📋 Test Case Management
| Tool | Functionality |
|------|-------------|
| `get_cases` | Query test cases with advanced filtering (priority, template, type, etc.) and pagination. |
| `get_case` | Fetch complete, structured details of a specific test case, including custom steps and fields. |
| `add_case` | Seamlessly create a new test case equipped with robust custom field validation. |
| `update_case` | Modify an existing test case's steps, metadata, or titles. |
| `update_cases` | Execute bulk-updates on multiple test cases simultaneously to save time. |

### ▶️ Test Execution & Tracking
| Tool | Functionality |
|------|-------------|
| `query_run` | Retrieve a single test run (`action: "one"`) or all test runs for a project (`action: "many"`, supporting filters). |
| `mutate_run` | Create a new test run or update an existing one in TestRail. |
| `get_tests` | Retrieve individual tests for a specific test run, with optional status filtering. |
| `get_results` | Retrieve paginated results for a specific test ID. |
| `add_results` | Submit test results to a test run using the specific `test_id`. |
| `add_results_for_cases` | Submits results to a run mapping directly to `case_id`s, streamlining automation workflows. |
| `add_attachment_to_run` | Attach logs, files, or zipped artifacts directly to an ongoing test run. |

### 🔗 Shared Steps (Optional)
| Tool | Functionality |
|------|-------------|
| `get_shared_steps` | List shared test steps for a project with optional reference filtering. |