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

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

1. Build and start:

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

1. View logs:

   docker-compose logs -f testrail-mcp

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

1. Install dependencies:

   pip install -r requirements.txt

1. Copy env and set credentials:

   cp env.example .env
   # Edit `.env` with your TestRail credentials:**

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": "..." } }