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

1. Clone this repository:

git clone <repository-url>
cd mcp-testrail

2. Install dependencies:

npm install

3. 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

1. Log in to your TestRail instance
2. Go to your user profile (click on your name in the top-right corner)
3. Navigate to the "API Keys" tab
4. Generate a new API key
5. 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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

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