# TestRail MCP Server

A Model Context Protocol (MCP) server for TestRail integration, providing comprehensive access to TestRail's test management functionality through MCP tools.

## Features

This MCP server provides tools for:

- **Projects**: List and retrieve TestRail projects
- **Test Cases**: Create, read, update, and delete test cases
- **Test Runs**: Manage test runs (create, update, close, delete)
- **Test Results**: Add and retrieve test results (single and bulk operations)
- **Sections**: Organize test cases with sections

## Prerequisites

- Node.js 18 or higher
- A TestRail instance with API access
- TestRail API key (generate from your TestRail account settings)

## Installation

1. Clone or download this repository
2. Install dependencies:

```bash
npm install
```

3. Build the project:

```bash
npm run build
```

4. Create a `.env` file in the project root with your TestRail credentials:

```bash
cp .env.example .env
```

Edit `.env` with your credentials:

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

## Configuration for Claude Code

To use this MCP server with Claude Code, add it to your MCP settings file:

**macOS/Linux**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "testrail": {
      "command": "node",
      "args": ["/absolute/path/to/testrail-mcp-server/dist/index.js"],
      "env": {
        "TESTRAIL_URL": "https://your-instance.testrail.io",
        "TESTRAIL_USERNAME": "your-email@example.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}
```

Or if you prefer to use the `.env` file:

```json
{
  "mcpServers": {
    "testrail": {
      "command": "node",
      "args": ["/absolute/path/to/testrail-mcp-server/dist/index.js"]
    }
  }
}
```

## Available Tools

### Projects

- `testrail_get_projects` - Get all projects
- `testrail_get_project` - Get a specific project by ID

### Test Cases

- `testrail_get_cases` - Get test cases from a project (optionally filtered by suite)
- `testrail_get_case` - Get a specific test case by ID
- `testrail_add_case` - Create a new test case in a section
- `testrail_update_case` - Update an existing test case
- `testrail_delete_case` - Delete a test case

### Test Runs

- `testrail_get_runs` - Get all test runs in a project
- `testrail_get_run` - Get a specific test run by ID
- `testrail_add_run` - Create a new test run
- `testrail_update_run` - Update an existing test run
- `testrail_close_run` - Close a test run
- `testrail_delete_run` - Delete a test run

### Test Results

- `testrail_get_results` - Get test results for a specific test
- `testrail_get_results_for_case` - Get test results for a test case in a run
- `testrail_get_results_for_run` - Get all test results for a test run
- `testrail_add_result` - Add a test result for a specific test
- `testrail_add_result_for_case` - Add a test result for a case in a test run
- `testrail_add_results` - Add multiple test results (bulk operation)
- `testrail_add_results_for_cases` - Add multiple test results for cases (bulk operation)

### Sections

- `testrail_get_sections` - Get sections from a project (optionally filtered by suite)
- `testrail_get_section` - Get a specific section by ID
- `testrail_add_section` - Create a new section
- `testrail_update_section` - Update an existing section
- `testrail_delete_section` - Delete a section

## Usage Examples

Once configured, you can use these tools through Claude Code. Here are some example prompts:

### Getting Projects
```
List all TestRail projects
```

### Creating a Test Case
```
Create a new test case in section 123 with title "Test user login" and priority High
```

### Adding Test Results
```
Add a passed test result for test case 456 in run 789 with comment "All checks passed"
```

### Creating a Test Run
```
Create a new test run called "Sprint 24 Testing" for project 1
```

## TestRail Status IDs

When adding test results, use these status IDs:

- `1` - Passed
- `2` - Blocked
- `3` - Untested (retest)
- `4` - Retest
- `5` - Failed

## TestRail Priority IDs

When creating or updating test cases, use these priority IDs:

- `1` - Low
- `2` - Medium
- `3` - High
- `4` - Critical

## Development

### Project Structure

```
testrail-mcp-server/
├── src/
│   ├── index.ts              # Main MCP server implementation
│   └── testrail-client.ts    # TestRail API client
├── dist/                     # Compiled JavaScript output
├── package.json
├── tsconfig.json
├── .env.example
└── README.md
```

### Building

```bash
npm run build
```

### Watching for Changes

```bash
npm run watch
```

### Running Locally

```bash
npm start
```

## Troubleshooting

### Connection Issues

1. Verify your TestRail credentials are correct
2. Check that your TestRail instance URL is accessible
3. Ensure your API key has the necessary permissions
4. Check the Claude Code logs for detailed error messages

### API Errors

- **401 Unauthorized**: Invalid credentials or API key
- **403 Forbidden**: Insufficient permissions for the requested operation
- **404 Not Found**: Resource (project, case, run, etc.) not found
- **429 Too Many Requests**: Rate limit exceeded, wait and retry

## API Reference

For more details on TestRail's API, see the [official TestRail API documentation](https://support.testrail.com/hc/en-us/articles/7077819312404-API-documentation).

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## Security

Never commit your `.env` file or expose your TestRail API credentials. Always use environment variables or secure credential storage.