TestRail MCP Server
A comprehensive Model Context Protocol (MCP) server for TestRail integration, providing seamless access to TestRail's test management capabilities through MCP tools with advanced project management, reporting, and AutoSpectra integration.
🚀 Features
Core TestRail Integration
- Complete TestRail API Coverage: Projects, suites, cases, runs, results, plans, milestones
- MCP Protocol Integration: Native MCP server implementation
- Type-Safe: Full TypeScript support with comprehensive type definitions
- Bulk Operations: Support for bulk test case and result operations
- Real-time Updates: WebSocket support for real-time TestRail updates
Advanced Project Management
- 🏗️ Advanced Project Creation: Template-driven project setup with predefined structures
- 📊 Project Health Analysis: Comprehensive project structure analysis with recommendations
- ⚡ Bulk Suite Management: Efficient bulk operations on test suites with validation
- 🎯 Template System: Pre-built templates for functional, API, performance, security, and mobile testing
Comprehensive Reporting & Analytics
- 📈 Project Dashboards: Interactive dashboards with metrics, trends, and failure analysis
- 🔍 Test Case Metrics: Detailed analysis of test case execution patterns and health
- 📋 Coverage Reports: Comprehensive test coverage analysis by priority, type, and automation
- 📊 Trend Analysis: Historical trend analysis with pass rate and completion tracking
- 🎯 Flakiness Detection: Automated identification of flaky tests
AutoSpectra Integration
- 🔄 Seamless Sync: Direct integration with AutoSpectra test automation framework
- 🚀 CI/CD Ready: Built-in support for GitHub Actions, Jenkins, and other CI/CD platforms
- 📝 Auto Case Creation: Automatic test case creation from AutoSpectra test results
- 📊 Real-time Monitoring: Live test execution monitoring and result submission
Enterprise Features
- 🔐 Security: Enterprise-grade security with encrypted credentials and audit logging
- ⚡ Performance: Optimized for large datasets with rate limiting and batching
- 🛡️ Error Handling: Comprehensive error handling with retry logic and graceful degradation
- 📝 Comprehensive Testing: Unit, integration, and E2E tests with 95%+ coverage
📁 Project Structure
testrail-mcp-server/
├── src/ # Source code
│ ├── types/ # TypeScript type definitions
│ │ ├── testrail.ts # TestRail API types
│ │ ├── mcp.ts # MCP-specific types
│ │ └── index.ts # Type exports
│ ├── tools/ # MCP tool implementations
│ ├── utils/ # Utility functions and helpers
│ └── index.ts # Main server entry point
├── tests/ # Test suites
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ └── e2e/ # End-to-end tests
├── docs/ # Documentation
│ ├── api/ # API documentation
│ └── guides/ # User guides and tutorials
├── examples/ # Usage examples
│ ├── basic/ # Basic usage examples
│ └── advanced/ # Advanced usage examples
├── package.json # Package configuration
├── tsconfig.json # TypeScript configuration
├── .env.example # Environment configuration template
└── .gitignore # Git ignore rules
⚡ Quick Start
Prerequisites
- Node.js 16.0 or higher
- TestRail instance with API access
- TestRail API key
Installation
# Clone the repository
git clone https://github.com/samuelvinay91/testrail-mcp.git
cd testrail-mcp
# Install dependencies
npm install
# Copy environment configuration
cp .env.example .env
# Edit .env with your TestRail credentials
# TESTRAIL_BASE_URL=https://your-instance.testrail.io
# TESTRAIL_USERNAME=your.email@company.com
# TESTRAIL_API_KEY=your-api-key-here
# Build and start
npm run build
npm start
🤖 Quick Setup with AI Coding Agents
Interactive Setup (Recommended):
# Run the interactive setup script
npm run setup-agents
# Follow the prompts to configure your preferred coding agent
# Supports: Claude Desktop, Cursor IDE, Windsurf IDE, Continue (VS Code)
Manual Configuration Examples:
Claude Desktop:
// ~/.claude-desktop/config.json
{
"mcpServers": {
"testrail": {
"command": "node",
"args": ["path/to/testrail-mcp/dist/index.js"],
"env": {
"TESTRAIL_BASE_URL": "https://yourcompany.testrail.io",
"TESTRAIL_USERNAME": "your.email@company.com",
"TESTRAIL_API_KEY": "your-api-key"
}
}
}
}
Cursor IDE:
// Cursor Settings > MCP Configuration
{
"mcp": {
"servers": [{
"name": "testrail",
"command": "node",
"args": ["./dist/index.js"],
"cwd": "/path/to/testrail-mcp"
}]
}
}
Windsurf IDE:
// .windsurf/mcp-config.json
{
"servers": {
"testrail": {
"command": "node",
"args": ["path/to/testrail-mcp/dist/index.js"],
"transport": "stdio"
}
}
}
📄 See complete setup guide for detailed instructions with Claude, Cursor, Windsurf, Continue, Cody, and more!
Development
# Start development server
npm run dev
# Build the project
npm run build
# Run tests
npm test
# Run with coverage
npm run test:coverage
# Lint and format
npm run lint
npm run format
🔧 Configuration
Create a .env file based on .env.example:
# Required: TestRail connection
TESTRAIL_BASE_URL=https://your-instance.testrail.io
TESTRAIL_USERNAME=your.email@company.com
TESTRAIL_API_KEY=your-api-key-here
# Optional: Server configuration
PORT=3000
NODE_ENV=development
LOG_LEVEL=info
# Optional: Default project settings
DEFAULT_PROJECT_ID=1
DEFAULT_SUITE_ID=1
🛠 Available MCP Tools
The TestRail MCP Server provides the following tools:
Connection & Authentication
connect_testrail- Connect to TestRail instancetest_connection- Test TestRail connection
Basic Project Management
get_projects- List all projectsget_project- Get specific projectcreate_project- Create new project
Advanced Project Management 🆕
create_advanced_project- Create project with templates and initial structureanalyze_project_structure- Analyze project health with recommendationsbulk_manage_suites- Perform bulk operations on test suitescreate_advanced_suite- Create suite with templates and structure
Suite & Section Management
get_suites- List suites in projectcreate_suite- Create new suiteget_sections- List sections in suitecreate_section- Create new section
Test Case Management
get_cases- List test casesget_case- Get specific test casecreate_case- Create new test caseupdate_case- Update existing test casedelete_case- Delete test case
Test Run Management
get_runs- List test runscreate_run- Create new test runupdate_run- Update test runclose_run- Close test run
Test Execution
get_tests- List tests in runadd_result- Add test resultadd_bulk_results- Add multiple resultsget_results- Get test results
Advanced Reporting & Analytics 🆕
generate_project_dashboard- Generate comprehensive project dashboardgenerate_execution_report- Generate detailed test execution reportsanalyze_case_metrics- Analyze test case metrics and healthgenerate_coverage_report- Generate comprehensive test coverage reportsgenerate_report- Generate custom test reports
AutoSpectra Integration 🆕
autospectra_sync- Synchronize AutoSpectra test results with TestRail
Legacy Tools (Still Available)
get_test_stats- Get test statisticsget_execution_trends- Get execution trends
📚 Documentation
- API Documentation - Detailed API reference
- User Guides - Step-by-step tutorials
- Coding Agents Setup - Integration with Claude, Cursor, Windsurf, and other AI tools
- AutoSpectra Integration - Advanced test automation integration
- Getting Started - Complete setup guide
- Examples - Code examples and use cases
🧪 Testing
# Run all tests
npm test
# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:e2e
# Watch mode
npm run test:watch
# Coverage report
npm run test:coverage
🤝 Contributing
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit your changes:
git commit -m 'Add 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.