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
TESTRAIL_USERNAME=your-email@example.com
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": "your-email@company.com",
        "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": "your-email@company.com",
        "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

Test Suites

Sections

Test Cases

Test Runs

Tests

Results

Test Plans

Milestones

Users

Statuses & Priorities

Templates & Configurations

Attachments

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:

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