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

Using npx (Recommended)

No installation required - run directly:

npx testrail-mcp

Global Installation

npm install -g testrail-mcp

Local Installation

npm install 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", "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", "mcp-testrail"],
      "env": {
        "TESTRAIL_URL": "https://your-company.testrail.io",
        "TESTRAIL_USERNAME": "[email protected]",
        "TESTRAIL_API_KEY": "your-api-key-here"
      }
    }
  }
}

Getting Your TestRail API Key

Log in to your TestRail instance
Go to My Settings (click your name in the top right)
Navigate to the API Keys tab
Click Add Key to generate a new API key
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.

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

License

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

Author

Ruslan Sapun

GitHub: @TenBarrel6