janainarocha/testrail-mcp-server

TestRail MCP Server

A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with TestRail for automated test case management and execution. This server provides complete TestRail REST API v2 coverage with 80 MCP tools.

🚀 Complete TestRail Integration

• ✅ 80 MCP Tools - Most comprehensive TestRail integration available
• ✅ 21 API Modules - Full TestRail REST API v2 coverage

🚀 Two Ways to Use

Option 1: Quick Setup (Recommended)

Add this to your VS Code mcp.json file:

{
  "servers": {
    "testrail": {
      "command": "npx",
      "args": [
        "-y",
        "github:janainarocha/testrail-mcp-server#v1.0.0"
      ],
      "type": "stdio",
      "env": {
        "TESTRAIL_URL": "https://yourcompany.testrail.io",
        "TESTRAIL_USER": "your.email@company.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

That's it! Restart VS Code and use MCP commands directly.

Option 2: Local Installation

1. Clone and install:

git clone https://github.com/janainarocha/testrail-mcp-server.git
cd testrail-mcp-server
npm install
npm run build

2. Add to VS Code mcp.json with your credentials:

{
  "servers": {
    "testrail": {
      "command": "node",
      "args": [
        "/path/to/testrail-mcp-server/dist/index.js"
      ],
      "type": "stdio",
      "env": {
        "TESTRAIL_URL": "https://yourcompany.testrail.io",
        "TESTRAIL_USER": "your.email@company.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

🔧 Setup Instructions

1. Get Your TestRail API Key

1. Log in to TestRail
2. Go to My Account → API Keys
3. Click Add Key
4. Copy the generated key

2. Configure VS Code

Add to your global VS Code MCP configuration file:

• Windows: %APPDATA%\Code\User\mcp.json
• Mac: ~/Library/Application Support/Code/User/mcp.json
• Linux: ~/.config/Code/User/mcp.json

3. Update Configuration

Replace your.email@company.com and your-api-key with your actual credentials.

4. Restart VS Code

🛠️ Prerequisites

• Node.js 18+ (for local installation)
• VS Code with GitHub Copilot extension
• TestRail account with API access
• TestRail API key (get from My Settings > API Keys)

💬 Usage Examples

Get Started: TestRail Context & Capabilities

#testrail_get_capabilities

This command provides complete TestRail platform context, terminology, and all available MCP tools - perfect for AI to understand TestRail concepts and workflows.

Export Test Cases in Bulk

#testrail_bulk_export_cases project_id: 1 suite_id: 5 include_steps: true

List Projects

#testrail_list_projects

Create Test Cases

#testrail_create_test_case
title: "Test successful user authentication"
section_id: 5
custom_expected: "User should be redirected to dashboard"
priority_id: 3

Explore Structure

#testrail_get_project project_id: 1
#testrail_list_sections project_id: 1 suite_id: 2
#testrail_get_case case_id: 456

Create Sections

#testrail_add_section suite_id: 3 name: "API Tests"

🔍 Troubleshooting

Server Not Appearing

• Check VS Code mcp.json file location and syntax
• Restart VS Code completely
• Verify GitHub Copilot extension is installed and active

Commands Not Working

• Ensure you're using GitHub Copilot Chat (not regular terminal)
• Use exact tool names (e.g., testrail_list_projects)
• Check VS Code output logs for detailed error messages
• Verify your TestRail permissions for the requested operation

👀 Read Operations (30+ tools)

➕ Create Operations (15+ tools)

� Update Operations (20+ tools)

� Delete Operations (10+ tools - Requires Confirmation)

📄 License

MIT License - see LICENSE for details.

🆘 Support

For issues and questions:

1. Check the troubleshooting section above
2. Open an issue on GitHub