hersonoliveira/testrail-mcp-server

TestRail MCP Server

This project is an MCP (Model Context Protocol) server that provides tools and resources for interacting with the TestRail API.

Installation

1. Clone the repository:

   git clone git@github.com:hersonoliveira/testrail-mcp-server.git
   

2. Navigate to the project directory:

   cd testrail-mcp-server
   

3. Install dependencies using uv:

   uv sync
   

Configuration

The server requires a configuration file with your TestRail instance details and API key. Create a file named .env in the project root with the following content:

TESTRAIL_URL=http://example.testrail.io
TESTRAIL_USERNAME=test@example.com
TESTRAIL_API_KEY=your_testrail_api_key

Running the Server

To start the MCP server, run the following command:

uv run mcp-testrail

Or using Python module syntax:

uv run python -m mcp_testrail

The server will start and be available for connection by MCP clients.

Adding to Claude Code

Option 1: Using Claude CLI (Recommended)

The easiest way to add the server is using the Claude CLI:

claude mcp add --transport stdio testrail \
  --env TESTRAIL_URL=http://example.testrail.io \
  --env TESTRAIL_USERNAME=test@example.com \
  --env TESTRAIL_API_KEY=your_testrail_api_key \
  -- uvx --from git+https://github.com/hersonoliveira/testrail-mcp-server mcp-testrail

Replace the environment variable values with your actual TestRail credentials.

Option 2: Manual Configuration

Alternatively, add the following configuration to your Claude Code MCP settings file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "testrail": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/hersonoliveira/testrail-mcp-server",
        "mcp-testrail"
      ],
      "env": {
        "TESTRAIL_URL": "http://example.testrail.io",
        "TESTRAIL_USERNAME": "test@example.com",
        "TESTRAIL_API_KEY": "your_testrail_api_key"
      }
    }
  }
}

This will automatically download and run the server from GitHub when Claude Code starts.

Adding to Cline

Add the following configuration to cline MCP settings json:

{
  "mcpServers": {
    "testrail": {
      "command": "python",
      "args": [
        "-m",
        "mcp_testrail"
      ],
      "cwd": "/absolute/path/to/testrail-mcp-server",
      "env": {
        "TESTRAIL_URL": "http://example.testrail.io",
        "TESTRAIL_USERNAME": "test@example.com",
        "TESTRAIL_API_KEY": "your_testrail_api_key"
      }
    }
  }
}

This way the server doesn't need to be started, Cline handles that.

Available Tools

This MCP server provides a set of tools for interacting with the TestRail API, including:

• Getting projects, suites, cases, runs, and results.
• Adding, updating, and deleting projects, suites, cases, runs, and results.
• Managing milestones and plans.
• Adding and deleting attachments.
• Getting users and custom fields.

Refer to the tool definitions provided by the MCP server for detailed information on available tools and their parameters.

Contributing

Contributions are welcome! Please see the file for details.

License

This project is licensed under the MIT License. See the file for details.