# TestRail MCP Server
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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
```bash
npm i -g @tenbarrel6/testrail-mcp
```
### Local Installation
```bash
npm i @tenbarrel6/testrail-mcp
```
### Using npx
No installation required - run directly in downloaded github repository:
```bash
npx testrail-mcp
```
## Configuration
### Environment Variables
Create a `.env` file in your project root or set environment variables:
```env
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):
```json
{
"mcpServers": {
"testrail": {
"command": "npx",
"args": ["-y", "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):
```json
{
"mcpServers": {
"testrail": {
"command": "npx",
"args": ["-y", "mcp-testrail"],
"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
| 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
```bash
# 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](LICENSE) file for details.
## Author
**Ruslan Sapun**
- GitHub: [@TenBarrel6](https://github.com/TenBarrel6)
## Links
- [npm Package](https://www.npmjs.com/package/@tenbarrel6/testrail-mcp)
- [GitHub Repository](https://github.com/TenBarrel6/testrail-mcp)
- [TestRail API Documentation](https://support.testrail.com/hc/en-us/articles/7077039051412-Introduction-to-the-TestRail-API)
- [Model Context Protocol](https://modelcontextprotocol.io/)
