TestRail MCP Server

A Model Context Protocol (MCP) server that connects AI assistants to TestRail test management — search, create, update, and execute test cases using natural language.

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.

Claude Desktop

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": "your@email.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

Cursor

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": "your@email.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

Windsurf

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": "your@email.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

Other MCP Clients

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.

TestRail MCP Server · Built with the Model Context Protocol

_{Keywords: TestRail MCP Server, Model Context Protocol, TestRail API integration, AI test management, LLM testing tools, Claude TestRail, Cursor TestRail, Windsurf TestRail, test case automation, QA AI assistant, MCP server for testing, TestRail plugin, test run management, AI-powered QA}

testrail-mcp-server

Quick Install