TestRail MCP Server

A Model Context Protocol (MCP) server that provides integration with TestRail, allowing AI assistants to interact with TestRail projects, test cases, test runs, and results.

Features

Tools

get_projects: Retrieve all TestRail projects
get_project: Get details of a specific project
get_test_cases: Retrieve test cases with optional filtering
create_test_case: Create new test cases
get_test_runs: Retrieve test runs for a project
create_test_run: Create new test runs
add_test_result: Add test results to test runs
get_users: Retrieve TestRail users
test_connection: Test the connection to TestRail
parse_testrail_url: 🆕 Parse TestRail URLs and auto-call appropriate tools

Resources

testrail://projects: Access to all TestRail projects
testrail://users: Access to all TestRail users

Prompts

test_case_template: Generate comprehensive test case templates
test_run_summary: Generate detailed test run summary reports

Installation

Clone this repository:

git clone <repository-url>
cd mcp-testrail

Install dependencies:

npm install

Build the project:

npm run build

Configuration

Create a .env file in the root directory with your TestRail configuration:

TESTRAIL_URL=https://your-company.testrail.io
TESTRAIL_USERNAME=your-email@company.com
TESTRAIL_API_KEY=your-api-key
DEFAULT_PROJECT_ID=1

Getting TestRail API Credentials

Log in to your TestRail instance
Go to your user profile (click on your name in the top-right corner)
Navigate to the "API Keys" tab
Generate a new API key
Use your email address as the username and the generated key as the API key

Usage

With Claude Desktop

Add the server to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "testrail": {
      "command": "node",
      "args": ["/path/to/mcp-testrail/dist/index.js"],
      "env": {
        "TESTRAIL_URL": "https://your-company.testrail.io",
        "TESTRAIL_USERNAME": "your-email@company.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

Direct Usage

You can also run the server directly:

npm start

Or in development mode:

npm run dev

Development

Project Structure

src/
├── index.ts              # Main MCP server implementation
├── testrail-client.ts    # TestRail API client
└── types.ts              # TypeScript type definitions

Available Scripts

npm run build: Build the TypeScript project
npm run watch: Build and watch for changes
npm start: Start the compiled server
npm run dev: Start the server in development mode with ts-node
npm run lint: Lint the source code

Building

npm run build

Testing

Test the connection to TestRail:

npm run dev
# Then use the test_connection tool

API Coverage

This MCP server covers the following TestRail API endpoints:

Projects

GET /get_projects - Get all projects
GET /get_project/{id} - Get project details

Test Cases

GET /get_cases/{project_id} - Get test cases
GET /get_case/{id} - Get test case details
POST /add_case/{section_id} - Create test case
POST /update_case/{id} - Update test case

Test Runs

GET /get_runs/{project_id} - Get test runs
GET /get_run/{id} - Get test run details
POST /add_run/{project_id} - Create test run
POST /close_run/{id} - Close test run

Test Results

GET /get_results/{test_id} - Get test results
POST /add_result/{test_id} - Add test result
POST /add_result_for_case/{run_id}/{case_id} - Add result for specific case

Users

GET /get_users - Get all users
GET /get_user/{id} - Get user details

Suites & Sections

GET /get_suites/{project_id} - Get test suites
GET /get_sections/{project_id} - Get sections
GET /get_milestones/{project_id} - Get milestones

Examples

URL Parsing (New Feature!)

Simply paste any TestRail URL and get the data automatically:

// Parse a test case URL
{
  "url": "https://moneyforward.tmxtestrail.com/index.php?/cases/view/2322865"
}
// Automatically detects it's a test case and retrieves case ID 2322865

// Parse a test run URL  
{
  "url": "https://company.testrail.io/runs/view/456"
}
// Automatically detects it's a test run and retrieves run details

// Parse test cases list with filters
{
  "url": "https://company.testrail.io/cases/123?suite_id=5&section_id=10"
}
// Automatically retrieves filtered test cases

Creating a Test Case

// Using the create_test_case tool
{
  "sectionId": 123,
  "title": "Test user login functionality",
  "type_id": 1,
  "priority_id": 2,
  "custom_steps_separated": [
    {
      "content": "Navigate to login page",
      "expected": "Login page is displayed"
    },
    {
      "content": "Enter valid credentials",
      "expected": "User is logged in successfully"
    }
  ]
}

Adding Test Results

// Using the add_test_result tool
{
  "runId": 456,
  "caseId": 789,
  "status_id": 1, // Passed
  "comment": "Test executed successfully",
  "elapsed": "5m",
  "version": "v1.2.3"
}

Error Handling

The server includes comprehensive error handling and will return detailed error messages for:

Invalid TestRail credentials
Network connectivity issues
Invalid parameters
TestRail API errors

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

Check the TestRail API documentation
Verify your credentials and network connectivity
Check the server logs for detailed error messages
Open an issue in this repository

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

A Model Context Protocol server that provides integration with TestRail, allowing AI assistants to interact with TestRail projects, test cases, test runs, and results.

Related MCP Servers

Xcode MCP Server
PolarVista
A
security
F
license
A
quality
A Model Context Protocol server that enables AI assistants to build and test Xcode projects directly through a standardized interface, with capabilities for running tests, monitoring progress, and accessing logs in real-time.
Last updated -
18
12
46
Qase MCP Server
RayYokoyama
-
security
F
license
-
quality
A Model Context Protocol server that integrates with the Qase test management platform, allowing users to create and retrieve test cases, manage test runs, and interact with Qase projects.
Last updated -
8
1
MCP Toolkit
zxfgds
-
security
F
license
-
quality
A comprehensive Model Context Protocol server implementation that enables AI assistants to interact with file systems, databases, GitHub repositories, web resources, and system tools while maintaining security and control.
Last updated -
7
1
TestRail MCP Server
sker65
A
security
A
license
A
quality
A Model Context Protocol server that allows interaction with TestRail's core entities (projects, cases, runs, results, datasets) through a standardized protocol compatible with MCP clients like Claude Desktop.
Last updated -
23
7
MIT License

View all related MCP servers

TestRail MCP Server