npm version

Compatible with:

🌟 Why Choose TestRail MCP Server?

Managing test cases manually is tedious and error-prone. With the TestRail MCP Server, your AI assistant (whether it’s Claude, Cursor, Windsurf, or any MCP-compliant client) interacts directly with your TestRail instance. Instruct it to find test cases, draft new ones, kick off test runs, and record test results—all through natural conversation.

No context switching. No tedious copy-pasting. Just ask your AI.

✨ Key Features & Capabilities

🚀 Quick Start Guide

1. Obtain Your TestRail API Key

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

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"
      }
    }
  }
}

{
  "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"
      }
    }
  }
}

{
  "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"
      }
    }
  }
}

3. See It in Action

Once configured, turbo-charge your QA workflow by asking your AI assistant:

• "List all projects in TestRail to find the latest active project."
• "Show me all active users in the project to find the right assignee."
• "Show me all test cases in section 5 of project 3."
• "Create a comprehensive test case for 'Login Validation' with detailed steps."
• "Start a new test run containing cases from section 5."

🖥️ Command Line Interface (CLI) & CI/CD Automation

In addition to interacting via AI assistants, you can invoke any TestRail tool directly from shell scripts, terminal environments, and automated CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins) using testrail-cli or npx — with zero LLM overhead.

• Deterministic Execution: Returns standard Unix exit codes (0 on success, 1 on error).
• Pipeline-Native Output: Emits clean JSON to stdout for piping into tools like jq, while diagnostics and errors go to stderr.
• Zero Duplication: Reuses the exact same API client, retry logic, and validation schemas as the MCP server.

Invocation Methods

# Method 1: Direct npx subcommand (Recommended)
npx @uarlouski/testrail-mcp-server cli <command> [flags]

# Method 2: Global or local binary
testrail-cli <command> [flags]

# Method 3: Via package runner
npx -p @uarlouski/testrail-mcp-server testrail-cli <command> [flags]

Examples

Query Projects (query_project)

# List all active projects
npx @uarlouski/testrail-mcp-server cli query_project --action many

# Query a single project by ID
npx @uarlouski/testrail-mcp-server cli query_project --action one --project_id 1

Export Cases for Knowledge Base / RAG (export_cases_for_rag)

# Export all cases for a project into Markdown & metadata sidecars
npx @uarlouski/testrail-mcp-server cli export_cases_for_rag \
  --project_id 1 \
  --output_dir ./rag_exports

# Export specific cases by ID (comma-separated list)
npx @uarlouski/testrail-mcp-server cli export_cases_for_rag \
  --case_ids C101,C102,103 \
  --output_dir ./rag_exports

Command Discovery & Flag Documentation

# List all available commands
npx @uarlouski/testrail-mcp-server cli --help

# Show parameter options for a specific tool
npx @uarlouski/testrail-mcp-server cli query_project --help
npx @uarlouski/testrail-mcp-server cli export_cases_for_rag --help

⚙️ Environment Variables & Security Controls

⚠️ Deprecation Lifecycle & Features Scheduled for Removal

To ensure smooth transitions, deprecated tools remain available by default (TESTRAIL_ENABLE_DEPRECATED_TOOLS=true) and will be removed in future major releases:

💡 Token Tip: If you are not using legacy tools, set TESTRAIL_ENABLE_DEPRECATED_TOOLS=false in your environment to eliminate deprecated tool definitions from the LLM prompt and save tokens!

📚 Documentation & Complete Tool Reference

For a comprehensive guide, detailed configuration options, and a complete breakdown of all available tools, please visit our official documentation site:

👉 TestRail MCP Server Documentation

The documentation includes detailed explanations for:

• 🔭 Discovery & Navigation: Exploring projects, suites, and sections.
• 📋 Test Case Management: Fetching, creating, and bulk-updating test cases.
• ▶️ Execution & Tracking: Managing test runs and submitting test results.
• 📎 Attachments: Automatically zipping and uploading files or directories.
• 🔗 Shared Steps: Managing reusable step definitions.

🤝 Contributing

Open-source contributions are actively welcomed! Please feel free to open an issue for feature requests or submit a pull request for improvements.

📜 License

This project is securely licensed under the Apache License 2.0.

TestRail MCP Server · Engineered with the Model Context Protocol