🚀 Quick Start Guide

2. Configure Your MCP Client

Add the server to your chosen MCP client configuration. The Claude Desktop example is shown below; Cursor, Windsurf, and other clients use the same pattern (see the collapsible sections further down).

🤖 Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@uarlouski/testrail-mcp-server@latest"],
      "env": {
        "TESTRAIL_INSTANCE_URL": "https://your-instance.testrail.io",
        "TESTRAIL_USERNAME": "your@email.com",
        "TESTRAIL_API_KEY": "your-api-key",
        "TESTRAIL_ENABLE_SHARED_STEPS": "true"
      }
    }
  }
}

<details> <summary><strong>⌨️ Cursor</strong></summary>

Open Settings → Features → MCP and add a new configuration:

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@uarlouski/testrail-mcp-server@latest"],
      "env": {
        "TESTRAIL_INSTANCE_URL": "https://your-instance.testrail.io",
        "TESTRAIL_USERNAME": "your@email.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

<details> <summary><strong>🌊 Windsurf</strong></summary>

Update your Windsurf MCP configuration file:

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@uarlouski/testrail-mcp-server@latest"],
      "env": {
        "TESTRAIL_INSTANCE_URL": "https://your-instance.testrail.io",
        "TESTRAIL_USERNAME": "your@email.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

<details> <summary><strong>🌐 Other MCP Clients</strong></summary>

Any MCP-compliant client can utilize this server. The pattern is universal—point your client at the npx command with the required environment variables. </details>

⚙️ Environment Variables

---

🔗 Shared Steps (Optional)

1. Obtain Your TestRail API Key

Navigate to My Settings → API Keys in your TestRail platform and generate a new key for authentication.

🛠️ Complete Tool Reference

The TestRail MCP Server provides heavily typed, descriptive tools designed specifically for LLM interaction:

💡 Pro Tip: Handling Large Data Sets & Permissions - Large Data Sets: For list-based tools like get_cases and get_sections, you can supply the output_file parameter with an absolute file path. The server will bypass the LLM context window by writing the raw JSON directly to disk and returning a concise summary, allowing you to run external scripts against the export! - Intelligent User Fallback: When fetching users using get_users without admin rights, TestRail denies access globally. The server dynamically catches this permission restriction and falls back to polling all active projects in parallel, retrieving and deduplicating active users so assignees and reviewers can always be mapped.