Why TestRail MCP Server?

Managing test cases manually is tedious. With the TestRail MCP Server, your AI assistant (Claude, Cursor, Windsurf, or any MCP-compliant client) talks directly to TestRail. Ask it to find test cases, create new ones, kick off test runs, or report results — all through natural conversation.

No context switching. No copy-pasting. Just ask.

✨ Features

| Category | Capabilities | |----------|-------------| | 🔍 Discovery | Browse projects, suites, and sections to map your test organization | | 📋 Case Management | Fetch, create, update, and bulk-edit test cases with full custom field support | | ▶️ Test Execution | Create runs, record results, attach files, and track test statuses | | 🧠 Context-Aware | Exposes templates, field definitions, priorities, and case types so LLMs generate valid, well-structured test cases |

🚀 Quick Start

1. Get Your TestRail API Key

Navigate to My Settings → API Keys in your TestRail instance and generate a new key.

2. Configure Your MCP Client

Add the server to your MCP client configuration. Below are examples for popular clients.

Edit your claude_desktop_config.json:

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

Open Settings → MCP and add a new server:

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

Add to your Windsurf MCP configuration:

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

Any MCP-compliant client can use this server. The configuration pattern is the same — point it at the npx command with the required environment variables.

3. Start Using It

Once configured, ask your AI assistant things like:

• "List all projects in TestRail"
• "Show me the test cases in suite 1 of project 3"
• "Create a test case for login validation with steps"
• "Start a new test run with cases from section 5"
• "Mark test 42 as passed with a comment"

⚙️ Configuration

| Environment Variable | Description | Required | |---------------------|-------------|:--------:| | TESTRAIL_INSTANCE_URL | Your TestRail instance URL (e.g., https://example.testrail.io) | ✅ | | TESTRAIL_USERNAME | Your TestRail email address | ✅ | | TESTRAIL_API_KEY | Your TestRail API key (how to get one) | ✅ |

🛠️ Available Tools

Discovery

| Tool | Description | |------|-------------| | get_projects | List all available projects in your TestRail instance | | get_sections | Navigate the folder/section hierarchy of a test suite |

Test Case Management

| Tool | Description | |------|-------------| | get_cases | Query test cases with filtering by priority, template, type, and more — supports pagination and recursive section fetching | | get_case | Fetch complete details of a specific test case including steps and custom fields | | create_case | Create a new test case with full custom field support | | update_case | Modify an existing test case's fields, title, or steps | | update_cases | Bulk-update multiple test cases simultaneously |

Test Execution

| Tool | Description | |------|-------------| | add_run | Create a new test run in TestRail | | get_tests | Get tests for a run, optionally filtered by status | | add_results | Submit one or more test results to a run | | add_attachment_to_run | Attach a file or zipped folder to a test run |

Metadata

| Tool | Description | |------|-------------| | get_statuses | List all available test statuses (Passed, Failed, Blocked, etc.) | | get_case_fields | Retrieve custom field definitions and dropdown options | | get_templates | List available case templates for correct case structure |

🏗️ Development

Prerequisites

• Node.js 18+
• npm

Setup

git clone https://github.com/uarlouski/testrail-mcp-server.git
cd testrail-mcp-server
npm install

Build

npm run build

Run Tests

npm test

🤝 Contributing

Contributions are welcome! Please feel free to open an issue or submit a pull request.

📜 License

This project is licensed under the Apache License 2.0.