TestRail MCP Server

MCP server for interacting with TestRail test case management instances.

Configuration

Authentication: TestRail uses HTTP Basic Authentication with your username and an API key (generated under My Settings → API Keys in TestRail). It is recommended to create a dedicated API user account rather than using a personal account.

Option 1: config.json

cp config.json.example config.json
# Edit config.json with your API user credentials

Option 2: Environment Variables

export TESTRAIL_URL="https://example.testrail.io"
export TESTRAIL_USERNAME="api-user@example.com"
export TESTRAIL_API_KEY="your-testrail-api-key"
export TESTRAIL_VERIFY_SSL="true"

Installation

Option 1: Using uv (Recommended)

uv is a fast Python package manager. Install it first:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

No additional installation needed - uvx will handle dependencies automatically.

Option 2: Using pip

pip install bibliocommons-mcp-testrail
# or for development
pip install -e ".[dev]"

AI Client Setup

VS Code (with MCP Extension)

1. Install an MCP-compatible extension in VS Code
2. Open VS Code Settings (JSON): Cmd+Shift+P → "Preferences: Open User Settings (JSON)"
3. Add the server configuration:

{
  "mcp.servers": {
    "testrail": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/testrail", "bibliocommons-mcp-testrail"]
    }
  }
}

Alternative: Using python directly

{
  "mcp.servers": {
    "testrail": {
      "command": "python",
      "args": ["-m", "bibliocommons_mcp_testrail"]
    }
  }
}

Claude Desktop

1. Open Claude Desktop configuration:

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

2. Add the server configuration:

{
  "mcpServers": {
    "testrail": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/testrail", "bibliocommons-mcp-testrail"]
    }
  }
}

Alternative: Using python directly

{
  "mcpServers": {
    "testrail": {
      "command": "python",
      "args": ["-m", "bibliocommons_mcp_testrail"]
    }
  }
}

Kiro IDE

1. Open Kiro IDE settings
2. Navigate to MCP Servers configuration
3. Add the server:

{
  "mcpServers": {
    "testrail": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/testrail", "bibliocommons-mcp-testrail"]
    }
  }
}

Alternative: Using python directly

{
  "mcpServers": {
    "testrail": {
      "command": "python",
      "args": ["-m", "bibliocommons_mcp_testrail"]
    }
  }
}

Kiro CLI

1. Create or edit the MCP configuration file:

   • User level: ~/.kiro/settings/mcp.json
   • Project level: <project-root>/.kiro/settings/mcp.json

2. Add the server configuration:

{
  "mcpServers": {
    "testrail": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/testrail", "bibliocommons-mcp-testrail"]
    }
  }
}

Alternative: Using python directly

{
  "mcpServers": {
    "testrail": {
      "command": "python",
      "args": ["-m", "bibliocommons_mcp_testrail"]
    }
  }
}

Configuration Notes

• Replace /absolute/path/to/testrail/ with the actual path to your server directory
• Using uvx (default): Automatically manages dependencies in isolated environments (like npx for Node.js)
• Using python (alternative): Requires pip install bibliocommons-mcp-testrail first
• After adding the configuration, restart your AI client for changes to take effect

Docker

# Pull from Docker Hub (private)
docker pull bibliocommons/mcp-testrail:latest

# Run in stdio mode
docker run -i --rm \
  -v /path/to/config.json:/config.json:ro \
  bibliocommons/mcp-testrail:latest \
  --config /config.json

# Run in HTTP mode
docker run -d --rm \
  -v /path/to/config.json:/config.json:ro \
  -p 8000:8000 \
  bibliocommons/mcp-testrail:latest \
  --config /config.json --transport http --port 8000

# Run in expanded mode
docker run -i --rm \
  -v /path/to/config.json:/config.json:ro \
  bibliocommons/mcp-testrail:latest \
  --config /config.json --expanded

Web UI with Swagger

A REST API with interactive Swagger documentation is available:

python -m bibliocommons_mcp_testrail.webui

Access the Swagger UI at: [http://localhost:8000/docs]

The Web UI provides:

• Interactive API documentation
• Try-it-out functionality for all endpoints
• OpenAPI/Swagger specification
• REST API access to all MCP tools

Standalone MCP Server

python -m bibliocommons_mcp_testrail

CLI Flags

Flag	Env Var	Description
--config PATH	TESTRAIL_CONFIG	Path to config.json
--read-only	TESTRAIL_READ_ONLY	Exclude destructive tools (add/update/delete operations)
--expanded	TESTRAIL_EXPANDED	Register all tools individually instead of gateway mode
--transport stdio|http	TESTRAIL_TRANSPORT	Transport mode (default: stdio)
--port PORT	TESTRAIL_PORT	HTTP port (default: 8000)
--version	—	Show version and exit

Gateway Mode (Default)

By default, the server exposes 2 tools instead of 40+ individual tools:

Tool	Purpose
testrail_api	Execute any TestRail action by name with a params dict
testrail_help	Search available actions, parameters, and descriptions

The AI assistant calls testrail_help to discover available actions, then calls testrail_api(action="get_cases", params={"project_id": 1, "suite_id": 5}) to execute them.

To register all individual tools (previous behavior), use --expanded:

python -m bibliocommons_mcp_testrail --expanded

Available Tools

Projects

• get_projects - List all projects
• get_project - Get project by ID
• add_project - Create a new project
• update_project - Update a project
• delete_project - Delete a project

Suites

• get_suites - List suites for a project
• get_suite - Get suite by ID
• add_suite - Create a new suite
• update_suite - Update a suite
• delete_suite - Delete a suite

Cases

• get_case - Get test case by ID (full details)
• get_cases - List test cases for a project with optional filters
• add_case - Create a new test case
• update_case - Update a test case
• update_cases - Bulk update multiple test cases
• delete_case - Delete a test case
• get_case_types - List available case types
• get_case_fields - List available case fields
• copy_to_section - Copy test cases to a section
• move_to_section - Move test cases to a section
• get_case_history - Get change history for a test case
• get_bdd - Export BDD test case as .feature file
• add_bdd - Import BDD .feature file into a section

Sections

• get_section - Get section by ID
• get_sections - List sections for a project
• add_section - Create a new section
• move_section - Move a section
• update_section - Update a section
• delete_section - Delete a section

Runs

• get_runs - List test runs for a project
• get_run - Get test run by ID
• add_run - Create a new test run
• update_run - Update a test run
• close_run - Close a test run
• delete_run - Delete a test run

Tests

• get_tests - List tests in a run
• get_test - Get test by ID

Results

• get_results - Get results for a test
• get_results_for_case - Get results for a case in a run
• get_results_for_run - Get all results for a run
• add_result_for_case - Add a result for a case in a run
• add_results_for_cases - Bulk add results for multiple cases

Plans

• get_plans - List test plans for a project
• get_plan - Get test plan by ID
• add_plan - Create a new test plan

Milestones

• get_milestones - List milestones for a project
• get_milestone - Get milestone by ID

Shared Steps

• get_shared_steps - List shared steps for a project
• get_shared_step - Get shared step by ID