macromill-mint/TestRail-MCP

TestRail MCP Server

A Model Context Protocol (MCP) server for TestRail API integration that enables AI assistants to interact with TestRail programmatically.

🚀 Overview

This package provides a clean TestRail MCP server that exposes TestRail API functionality through the Model Context Protocol. It allows AI assistants and other MCP-compatible tools to:

• Query TestRail projects, test cases, and test runs
• Create and manage test runs and milestones
• Add test results and update test statuses
• Integrate TestRail data into AI workflows

📦 Installation

Option 1: Install from GitHub (Recommended)

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

# Install the package
pip install -e .

Option 2: Manual Installation

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

# Install dependencies
pip install -r requirements.txt

⚙️ Configuration

1. Copy the environment template:

   cp env.example .env
   

2. Edit .env with your TestRail credentials:

   TESTRAIL_BASE_URL=https://your-instance.testrail.io
   TESTRAIL_USERNAME=your-email@example.com
   TESTRAIL_API_KEY=your-api-key
   

3. Get your TestRail API key:

   • Log into your TestRail instance
   • Go to User Settings → API & Integrations
   • Generate a new API key
   • Copy the key to your .env file

🚀 Usage

Test Connection:

python3 list_projects.py

Run the MCP Server:

python3 testrail_mcp_server.py

Integration with AI Assistants:

This MCP server can be integrated with AI assistants that support the Model Context Protocol. Here's how to configure it:

1. Add to your MCP configuration:

   {
     "mcpServers": {
       "testrail": {
         "command": "python3",
         "args": ["/path/to/testrail-mcp-server/testrail_mcp_server.py"]
       }
     }
   }
   

2. Use in AI workflows:

   • Query TestRail projects and test cases
   • Create test runs and milestones
   • Add test results and update statuses
   • Generate test reports and analytics

🎯 Available MCP Tools

The server exposes the following TestRail API endpoints as MCP tools:

📁 Project Structure

testrail-mcp-server/
├── testrail_mcp_server.py        # Core MCP Server
├── list_projects.py              # Utility script
├── requirements.txt              # Dependencies
├── env.example                   # Environment template
├── mcp_config.json              # MCP configuration
├── setup.py                     # Package setup
├── LICENSE                      # MIT License
├── .gitignore                   # Git ignore rules
└── README.md                    # This file

🛠️ Development

Adding New Tools:

1. Add the API method to TestRailClient class
2. Define the tool in handle_list_tools()
3. Implement the tool handler in handle_call_tool()

Testing:

# Test connection
python3 list_projects.py

# Run server
python3 testrail_mcp_server.py

Building Package:

# Build distribution
python3 -m build

# Install locally
pip install -e .

📚 API Reference

The server implements the TestRail REST API v2. For detailed API documentation, see:

• TestRail API Documentation

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add 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 file for details.

🆘 Support

• Issues: GitHub Issues
• Documentation: GitHub Wiki
• Discussions: GitHub Discussions

🙏 Acknowledgments

• TestRail for the excellent test management platform
• Model Context Protocol for the MCP specification