TestRail MCP Server

A Model Context Protocol (MCP) server for TestRail integration, providing comprehensive access to TestRail's test management functionality through MCP tools.

Features

This MCP server provides tools for:

• Projects: List and retrieve TestRail projects
• Test Cases: Create, read, update, and delete test cases
• Test Runs: Manage test runs (create, update, close, delete)
• Test Results: Add and retrieve test results (single and bulk operations)
• Sections: Organize test cases with sections

Prerequisites

• Node.js 18 or higher
• A TestRail instance with API access
• TestRail API key (generate from your TestRail account settings)

Installation

1. Clone or download this repository
2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Create a .env file in the project root with your TestRail credentials:

cp .env.example .env

Edit .env with your credentials:

TESTRAIL_URL=https://your-instance.testrail.io
TESTRAIL_USERNAME=your-email@example.com
TESTRAIL_API_KEY=your-api-key

Configuration for Claude Code

To use this MCP server with Claude Code, add it to your MCP settings file:

macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Or if you prefer to use the .env file:

{
  "mcpServers": {
    "testrail": {
      "command": "node",
      "args": ["/absolute/path/to/testrail-mcp-server/dist/index.js"]
    }
  }
}

Available Tools

Projects

• testrail_get_projects - Get all projects
• testrail_get_project - Get a specific project by ID

Test Cases

• testrail_get_cases - Get test cases from a project (optionally filtered by suite)
• testrail_get_case - Get a specific test case by ID
• testrail_add_case - Create a new test case in a section
• testrail_update_case - Update an existing test case
• testrail_delete_case - Delete a test case

Test Runs

• testrail_get_runs - Get all test runs in a project
• testrail_get_run - Get a specific test run by ID
• testrail_add_run - Create a new test run
• testrail_update_run - Update an existing test run
• testrail_close_run - Close a test run
• testrail_delete_run - Delete a test run

Test Results

• testrail_get_results - Get test results for a specific test
• testrail_get_results_for_case - Get test results for a test case in a run
• testrail_get_results_for_run - Get all test results for a test run
• testrail_add_result - Add a test result for a specific test
• testrail_add_result_for_case - Add a test result for a case in a test run
• testrail_add_results - Add multiple test results (bulk operation)
• testrail_add_results_for_cases - Add multiple test results for cases (bulk operation)

Sections

• testrail_get_sections - Get sections from a project (optionally filtered by suite)
• testrail_get_section - Get a specific section by ID
• testrail_add_section - Create a new section
• testrail_update_section - Update an existing section
• testrail_delete_section - Delete a section

Usage Examples

Once configured, you can use these tools through Claude Code. Here are some example prompts:

Getting Projects

List all TestRail projects

Creating a Test Case

Create a new test case in section 123 with title "Test user login" and priority High

Adding Test Results

Add a passed test result for test case 456 in run 789 with comment "All checks passed"

Creating a Test Run

Create a new test run called "Sprint 24 Testing" for project 1

TestRail Status IDs

When adding test results, use these status IDs:

• 1 - Passed
• 2 - Blocked
• 3 - Untested (retest)
• 4 - Retest
• 5 - Failed

TestRail Priority IDs

When creating or updating test cases, use these priority IDs:

• 1 - Low
• 2 - Medium
• 3 - High
• 4 - Critical

Development

Project Structure

testrail-mcp-server/
├── src/
│   ├── index.ts              # Main MCP server implementation
│   └── testrail-client.ts    # TestRail API client
├── dist/                     # Compiled JavaScript output
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

Building

npm run build

Watching for Changes

npm run watch

Running Locally

npm start

Troubleshooting

Connection Issues

1. Verify your TestRail credentials are correct
2. Check that your TestRail instance URL is accessible
3. Ensure your API key has the necessary permissions
4. Check the Claude Code logs for detailed error messages

API Errors

• 401 Unauthorized: Invalid credentials or API key
• 403 Forbidden: Insufficient permissions for the requested operation
• 404 Not Found: Resource (project, case, run, etc.) not found
• 429 Too Many Requests: Rate limit exceeded, wait and retry

API Reference

For more details on TestRail's API, see the official TestRail API documentation.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Security

Never commit your .env file or expose your TestRail API credentials. Always use environment variables or secure credential storage.