Skip to main content
Glama
testrail-mcp-server

testrail-mcp-server

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

Related MCP server: TestRail MCP Server

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
  1. Build the project:

npm run build
  1. 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.

Available Tools

25 tools
testrail_add_caseC

Create a new test case in a section

Inputs: title (required), section_id (required), refs, type_id, +6 more.

testrail_add_resultB

Add a test result for a specific test

Inputs: test_id (required), status_id (required), comment, defects, +3 more.

testrail_add_result_for_caseC

Add a test result for a case in a specific test run

Inputs: run_id (required), case_id (required), status_id (required), comment, +4 more.

testrail_add_resultsB

Add multiple test results for a test run (bulk operation)

Inputs: run_id (required), results (required).

testrail_add_results_for_casesC

Add multiple test results for cases in a test run (bulk operation)

Inputs: run_id (required), results (required).

testrail_add_runC

Create a new test run

Inputs: name (required), project_id (required), case_ids, suite_id, +4 more.

testrail_add_sectionC

Create a new section in a project

Inputs: name (required), project_id (required), suite_id, parent_id, +1 more.

testrail_close_runC

Close a test run

Inputs: run_id (required).

testrail_delete_caseC

Delete a test case

Inputs: case_id (required).

testrail_delete_runC

Delete a test run

Inputs: run_id (required).

testrail_delete_sectionC

Delete a section

Inputs: section_id (required).

testrail_get_caseC

Get a specific test case by ID

Inputs: case_id (required).

testrail_get_casesC

Get test cases from a project (optionally filtered by suite)

Inputs: project_id (required), suite_id.

testrail_get_projectB

Get a specific project by ID

Inputs: project_id (required).

testrail_get_projectsB

Get all projects from TestRail

Inputs: no named parameters.

testrail_get_resultsC

Get test results for a specific test

Inputs: test_id (required), limit.

testrail_get_results_for_caseB

Get test results for a specific test case in a run

Inputs: run_id (required), case_id (required), limit.

testrail_get_results_for_runC

Get all test results for a test run

Inputs: run_id (required), limit.

testrail_get_runC

Get a specific test run by ID

Inputs: run_id (required).

testrail_get_runsB

Get all test runs in a project

Inputs: project_id (required).

testrail_get_sectionB

Get a specific section by ID

Inputs: section_id (required).

testrail_get_sectionsB

Get sections from a project (optionally filtered by suite)

Inputs: project_id (required), suite_id.

testrail_update_caseC

Update an existing test case

Inputs: case_id (required), refs, title, estimate, +4 more.

testrail_update_runC

Update an existing test run

Inputs: run_id (required), name, description, milestone_id.

testrail_update_sectionC

Update an existing section

Inputs: section_id (required), name, description.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 25 tools

    Disambiguation4/5

    Most tools are clearly distinct by resource and action, but the result-related tools (testrail_get_results, testrail_get_results_for_case, testrail_get_results_for_run, testrail_add_result, testrail_add_result_for_case, testrail_add_results, testrail_add_results_for_cases) have subtle differences that may cause confusion. The bulk vs single and for_case vs for_run distinctions are not immediately obvious from names alone.

    Naming Consistency5/5

    All tools follow a consistent pattern: testrail_<verb>_<resource> (e.g., testrail_get_project, testrail_add_case). The prefix is uniform, verbs are consistent (get, add, update, delete), and resources are clear. Minor variations like 'get_results_for_case' are still predictable.

    Tool Count3/5

    25 tools is on the higher end and might feel heavy, but it covers a broad domain (projects, cases, runs, results, sections). However, some tools could be consolidated (e.g., result retrieval and addition variants) to reduce redundancy. The count is borderline but justified by the comprehensive CRUD operations.

    Completeness4/5

    The surface covers core entities (projects, cases, runs, results, sections) with full CRUD for cases, runs, and sections. However, projects only have get operations (no create/update/delete), and there is no tool for retrieving a single test result by ID. These are minor gaps that agents can work around by using list operations.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to interact with TestRail test management systems through comprehensive API integration. Supports retrieving and updating test cases, projects, suites, runs, and results, plus adding attachments and managing test data through natural language commands.
      18
      31 npm
      MIT
    • A
      license
      A
      quality
      F
      maintenance
      Enables management of TestRail projects, test cases, runs, and results directly through MCP-supported clients. It provides a comprehensive set of tools to interact with the TestRail API for seamless test cycle management within AI environments.
      42
      6,218 npm
      42
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for TestRail that enables AI agents to manage test cases, runs, and results, plus a bundled skill to convert Jira tickets into TestRail test cases.
      15
      MIT