TestRail MCP Server

A Model Context Protocol (MCP) server for seamless TestRail integration. This server enables AI assistants like Claude, Cursor, and other MCP-compatible clients to interact directly with your TestRail instance.

Features

• 🔐 Secure Authentication - API key-based authentication with TestRail
• 📊 Full TestRail API Coverage - Support for TestRail API v9.7.2
• 🚀 Easy Integration - Works with Cursor, Claude Desktop, and other MCP clients
• 📦 Zero Configuration - Run directly with npx

Installation

Global Installation

npm i -g @tenbarrel6/testrail-mcp

Local Installation

npm i @tenbarrel6/testrail-mcp

Using npx

No installation required - run directly in downloaded github repository:

npx @tenbarrel6/testrail-mcp

Configuration

Environment Variables

Create a .env file in your project root or set environment variables:

TESTRAIL_URL=https://your-domain.testrail.io
[email protected]
TESTRAIL_API_KEY=your-api-key-here

Cursor IDE Configuration

Add to your Cursor settings (.cursor/mcp.json or global settings):

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@tenbarrel6/testrail-mcp"],
      "env": {
        "TESTRAIL_URL": "https://your-company.testrail.io",
        "TESTRAIL_USERNAME": "[email protected]",
        "TESTRAIL_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@tenbarrel6/testrail-mcp"],
      "env": {
        "TESTRAIL_URL": "https://your-company.testrail.io",
        "TESTRAIL_USERNAME": "[email protected]",
        "TESTRAIL_API_KEY": "your-api-key-here"
      }
    }
  }
}

Getting Your TestRail API Key

1. Log in to your TestRail instance
2. Go to My Settings (click your name in the top right)
3. Navigate to the API Keys tab
4. Click Add Key to generate a new API key
5. Copy and save the key securely

Available Tools

Projects

| Tool | Description | |------|-------------| | get_projects | Get all TestRail projects | | get_project | Get a specific project by ID |

Test Suites

| Tool | Description | |------|-------------| | get_suites | Get all test suites for a project | | get_suite | Get a specific test suite by ID | | add_suite | Create a new test suite | | update_suite | Update an existing test suite |

Sections

| Tool | Description | |------|-------------| | get_sections | Get all sections for a project/suite | | get_section | Get a specific section by ID | | add_section | Create a new section | | update_section | Update an existing section | | delete_section | Delete a section | | move_section | Move a section to another parent or position |

Test Cases

| Tool | Description | |------|-------------| | get_cases | Get test cases for a project/suite | | get_case | Get a specific test case by ID | | add_case | Create a new test case | | update_case | Update an existing test case | | delete_case | Delete a test case | | delete_cases | Delete multiple test cases | | copy_cases_to_section | Copy test cases to another section | | move_cases_to_section | Move test cases to another section | | get_case_types | Get all available test case types | | get_case_fields | Get all available test case fields | | get_history_for_case | Get the edit history for a test case |

Test Runs

| Tool | Description | |------|-------------| | get_runs | Get test runs for a project | | get_run | Get a specific test run by ID | | add_run | Create a new test run | | update_run | Update an existing test run | | close_run | Close a test run | | delete_run | Delete a test run |

Tests

| Tool | Description | |------|-------------| | get_tests | Get tests for a test run | | get_test | Get a specific test by ID |

Results

| Tool | Description | |------|-------------| | get_results | Get results for a test | | get_results_for_case | Get results for a test case in a run | | get_results_for_run | Get all results for a test run | | add_result | Add a test result | | add_result_for_case | Add a test result for a specific case in a run | | add_results | Add multiple test results by test IDs | | add_results_for_cases | Add multiple test results for cases in a run |

Test Plans

| Tool | Description | |------|-------------| | get_plans | Get test plans for a project | | get_plan | Get a specific test plan by ID | | add_plan | Create a new test plan | | update_plan | Update an existing test plan | | close_plan | Close a test plan | | delete_plan | Delete a test plan | | add_plan_entry | Add test runs to a test plan | | update_plan_entry | Update a test plan entry | | delete_plan_entry | Delete a test plan entry | | add_run_to_plan_entry | Add a test run to an existing plan entry | | update_run_in_plan_entry | Update a test run inside a plan entry | | delete_run_from_plan_entry | Delete a test run from a plan entry |

Milestones

| Tool | Description | |------|-------------| | get_milestones | Get milestones for a project | | get_milestone | Get a specific milestone by ID | | add_milestone | Create a new milestone | | update_milestone | Update an existing milestone | | delete_milestone | Delete a milestone |

Users

| Tool | Description | |------|-------------| | get_users | Get all users (optionally filtered by project) | | get_user | Get a user by ID | | get_user_by_email | Get a user by email address | | get_current_user | Get the current authenticated user |

Statuses & Priorities

| Tool | Description | |------|-------------| | get_statuses | Get all available test result statuses | | get_case_statuses | Get all available test case statuses (Enterprise) | | get_priorities | Get all available test case priorities |

Templates & Configurations

| Tool | Description | |------|-------------| | get_templates | Get all templates for a project | | get_configs | Get all configurations for a project | | get_result_fields | Get all available result custom fields |

Attachments

| Tool | Description | |------|-------------| | add_attachment_to_case | Add an attachment to a test case | | add_attachment_to_result | Add an attachment to a test result | | add_attachment_to_run | Add an attachment to a test run | | add_attachment_to_plan | Add an attachment to a test plan | | add_attachment_to_plan_entry | Add an attachment to a test plan entry | | get_attachment | Get/download an attachment by ID | | get_attachments_for_case | Get all attachments for a test case | | get_attachments_for_test | Get all attachments for a test | | get_attachments_for_run | Get all attachments for a test run | | get_attachments_for_plan | Get all attachments for a test plan | | get_attachments_for_plan_entry | Get all attachments for a test plan entry | | delete_attachment | Delete an attachment |

Usage Examples

Once configured, you can interact with TestRail through your AI assistant:

Get all projects

"List all TestRail projects"

Create a test case

"Create a new test case in section 123 with title 'Verify login functionality'"

Add test results

"Add a passed result for test case 456 in run 789 with comment 'All checks passed'"

Get test run results

"Show me all results for test run 101"

Test Result Status IDs

When adding results, use these standard status IDs:

| Status ID | Status | |-----------|--------| | 1 | Passed | | 2 | Blocked | | 3 | Untested | | 4 | Retest | | 5 | Failed |

Development

Building from Source

# Clone the repository
git clone https://github.com/TenBarrel6/testrail-mcp.git
cd testrail-mcp

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run start - Run the compiled server
• npm run dev - Run in development mode with hot reload

Requirements

• Node.js 18+
• TestRail instance with API access enabled
• Valid TestRail API key

Troubleshooting

"Not authenticated" Error

Ensure your environment variables are correctly set:

• TESTRAIL_URL should include the protocol (https://)
• TESTRAIL_USERNAME should be your email address
• TESTRAIL_API_KEY should be a valid API key (not your password)

Connection Issues

• Verify your TestRail URL is accessible
• Check if API access is enabled in your TestRail administration settings
• Ensure your user has appropriate permissions

MCP Client Not Connecting

• Restart your MCP client (Cursor/Claude Desktop)
• Verify the configuration JSON syntax is valid
• Check that npx is available in your PATH

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Ruslan Sapun

• GitHub: @TenBarrel6

Links

• npm Package
• GitHub Repository
• TestRail API Documentation
• Model Context Protocol