TestRail MCP Server

# TestRail MCP Server A Model Context Protocol (MCP) server that provides integration with TestRail, allowing AI assistants to interact with TestRail projects, test cases, test runs, and results. ## Features ### Tools - **get_projects**: Retrieve all TestRail projects - **get_project**: Get details of a specific project - **get_test_cases**: Retrieve test cases with optional filtering - **create_test_case**: Create new test cases - **get_test_runs**: Retrieve test runs for a project - **create_test_run**: Create new test runs - **add_test_result**: Add test results to test runs - **get_users**: Retrieve TestRail users - **test_connection**: Test the connection to TestRail - **parse_testrail_url**: 🆕 Parse TestRail URLs and auto-call appropriate tools ### Resources - **testrail://projects**: Access to all TestRail projects - **testrail://users**: Access to all TestRail users ### Prompts - **test_case_template**: Generate comprehensive test case templates - **test_run_summary**: Generate detailed test run summary reports ## Installation 1. Clone this repository: ```bash git clone <repository-url> cd mcp-testrail ``` 2. Install dependencies: ```bash npm install ``` 3. Build the project: ```bash npm run build ``` ## Configuration Create a `.env` file in the root directory with your TestRail configuration: ```env TESTRAIL_URL=https://your-company.testrail.io TESTRAIL_USERNAME=your-email@company.com TESTRAIL_API_KEY=your-api-key DEFAULT_PROJECT_ID=1 ``` ### Getting TestRail API Credentials 1. Log in to your TestRail instance 2. Go to your user profile (click on your name in the top-right corner) 3. Navigate to the "API Keys" tab 4. Generate a new API key 5. Use your email address as the username and the generated key as the API key ## Usage ### With Claude Desktop Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`): ```json { "mcpServers": { "testrail": { "command": "node", "args": ["/path/to/mcp-testrail/dist/index.js"], "env": { "TESTRAIL_URL": "https://your-company.testrail.io", "TESTRAIL_USERNAME": "your-email@company.com", "TESTRAIL_API_KEY": "your-api-key" } } } } ``` ### Direct Usage You can also run the server directly: ```bash npm start ``` Or in development mode: ```bash npm run dev ``` ## Development ### Project Structure ``` src/ ├── index.ts # Main MCP server implementation ├── testrail-client.ts # TestRail API client └── types.ts # TypeScript type definitions ``` ### Available Scripts - `npm run build`: Build the TypeScript project - `npm run watch`: Build and watch for changes - `npm start`: Start the compiled server - `npm run dev`: Start the server in development mode with ts-node - `npm run lint`: Lint the source code ### Building ```bash npm run build ``` ### Testing Test the connection to TestRail: ```bash npm run dev # Then use the test_connection tool ``` ## API Coverage This MCP server covers the following TestRail API endpoints: ### Projects - `GET /get_projects` - Get all projects - `GET /get_project/{id}` - Get project details ### Test Cases - `GET /get_cases/{project_id}` - Get test cases - `GET /get_case/{id}` - Get test case details - `POST /add_case/{section_id}` - Create test case - `POST /update_case/{id}` - Update test case ### Test Runs - `GET /get_runs/{project_id}` - Get test runs - `GET /get_run/{id}` - Get test run details - `POST /add_run/{project_id}` - Create test run - `POST /close_run/{id}` - Close test run ### Test Results - `GET /get_results/{test_id}` - Get test results - `POST /add_result/{test_id}` - Add test result - `POST /add_result_for_case/{run_id}/{case_id}` - Add result for specific case ### Users - `GET /get_users` - Get all users - `GET /get_user/{id}` - Get user details ### Suites & Sections - `GET /get_suites/{project_id}` - Get test suites - `GET /get_sections/{project_id}` - Get sections - `GET /get_milestones/{project_id}` - Get milestones ## Examples ### URL Parsing (New Feature!) Simply paste any TestRail URL and get the data automatically: ```javascript // Parse a test case URL { "url": "https://moneyforward.tmxtestrail.com/index.php?/cases/view/2322865" } // Automatically detects it's a test case and retrieves case ID 2322865 // Parse a test run URL { "url": "https://company.testrail.io/runs/view/456" } // Automatically detects it's a test run and retrieves run details // Parse test cases list with filters { "url": "https://company.testrail.io/cases/123?suite_id=5&section_id=10" } // Automatically retrieves filtered test cases ``` ### Creating a Test Case ```javascript // Using the create_test_case tool { "sectionId": 123, "title": "Test user login functionality", "type_id": 1, "priority_id": 2, "custom_steps_separated": [ { "content": "Navigate to login page", "expected": "Login page is displayed" }, { "content": "Enter valid credentials", "expected": "User is logged in successfully" } ] } ``` ### Adding Test Results ```javascript // Using the add_test_result tool { "runId": 456, "caseId": 789, "status_id": 1, // Passed "comment": "Test executed successfully", "elapsed": "5m", "version": "v1.2.3" } ``` ## Error Handling The server includes comprehensive error handling and will return detailed error messages for: - Invalid TestRail credentials - Network connectivity issues - Invalid parameters - TestRail API errors ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests if applicable 5. Submit a pull request ## License MIT License - see LICENSE file for details. ## Support For issues and questions: 1. Check the TestRail API documentation 2. Verify your credentials and network connectivity 3. Check the server logs for detailed error messages 4. Open an issue in this repository