Skip to main content
Glama
test-rail-mcp
by kluchick

test-rail-mcp

Purpose

  • Lightweight Model Context Protocol (MCP) server that bridges Cursor (or any MCP client) to TestRail.

  • Exposes a tool get_case_by_id to fetch TestRail cases and return typed Pydantic models.

  • Configured via TESTRAIL_URL, TESTRAIL_USERNAME, TESTRAIL_PASSWORD; deploy via Docker or run locally.

  • Designed to be easily extended with more TestRail endpoints (runs, results, sections, etc.).

Related MCP server: TestRail MCP Server

Features

  • MCP over HTTP: Works with Cursor and other MCP clients.

  • Containerized: One-command Docker setup.

  • Extensible: Add more tools without changing the transport.

Setup

Docker Setup

  1. Update docker-compose.yml file with TestRail credentials

    TESTRAIL_URL=https://your-instance.testrail.com
    TESTRAIL_USERNAME=your-username
    TESTRAIL_PASSWORD=your-api-key
  2. Build and start:

    docker-compose up -d
    # or on Windows: run the bundled script
    .\run_docker.bat
  3. View logs:

    docker-compose logs -f testrail-mcp
  4. Stop:

    docker-compose down

Local Development

  1. Create and activate venv (macOS/Linux):

    python -m venv .venv
    source .venv/bin/activate

    Windows (PowerShell):

    .venv\Scripts\Activate.ps1
  2. Install dependencies:

    pip install -r requirements.txt
  3. Copy env and set credentials:

    cp env.example .env
    # Edit `.env` with your TestRail credentials:**
    ```sh
    TESTRAIL_URL=https://your-instance.testrail.com
    TESTRAIL_USERNAME=your-username
    TESTRAIL_PASSWORD=your-api-key
  4. Run locally:

    python code/server.py
    # server listens on http://localhost:8000

    Or use Docker (see above) which exposes http://localhost:8001.

Add to Cursor

Add to your Cursor mcp.json:

{
  "mcpServers": {
    "testrail": {
      "type": "http",
      "url": "http://localhost:8001/mcp"
    }
  }
}
  • If running locally without Docker, use http://localhost:8000/mcp.

  • Enable in Tools & Integrations, ensure the testrail MCP is enabled.

Tooling API

  • get_case_by_id: Fetch a case by numeric case_id.

Example result (shape):

{
  "id": 123,
  "title": "Verify login",
  "type_id": 1,
  "priority_id": 2,
  "section_id": 10,
  "suite_id": 3,
  "custom_fields": {
    "custom_steps": "...",
    "custom_expected": "..."
  }
}

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      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.
      23
      20
      MIT
    • A
      license
      B
      quality
      A
      maintenance
      AI-native Model Context Protocol (MCP) server for TestRail. Lets Claude, Cursor, Windsurf, and other AI assistants browse projects, create and update test cases, kick off test runs, and record results through natural-language conversation — with strongly-typed tool schemas and per-project custom field validation that helps LLMs generate valid TestRail requests on the first try.
      27
      1,151 npm
      45
      Apache 2.0
    • A
      license
      C
      quality
      D
      maintenance
      MCP server for TestRail API, providing AI assistants with 107 tools to manage test cases, runs, results, plans, and more. Supports API key, password, and SSO cookie authentication.
      54
      18 npm
      2
      MIT