·

What Is TestRail MCP

Learn what TestRail MCP is and how it lets your AI agent manage test cases, runs, and results.

TestRail has been the default test case repository for mid-size and enterprise QA orgs since long before "AI agent" was a job title on anyone's resume. What changed in the last two years isn't TestRail itself — it's that an MCP server now sits between your coding agent and TestRail's REST API, so Claude Code, Cursor, Gemini CLI, or OpenCode can read and write test cases, runs, and results without you copy-pasting JSON into Postman. This topic covers what the TestRail MCP server actually exposes, how it authenticates, what parts of the QA workflow it's realistic to automate today, and where teams get burned by letting an LLM write directly into a system of record that auditors and compliance teams also depend on.

The mental model to hold onto: TestRail MCP is a thin, typed wrapper around TestRail's existing index.php?/api/v2/ REST endpoints. It doesn't add new TestRail functionality — every tool call it exposes maps to an API call you could make with curl today. The value is that your agent can chain multiple calls (create a suite, add ten cases, create a run against those cases, post results) inside one conversational turn, using the requirement doc or acceptance criteria already open in your editor as the source material.

Core TestRail MCP Tools: Projects, Suites, Cases, Runs, and Results

Every TestRail MCP implementation I've used (the community server testrail-mcp on npm, and a couple of internal forks built on top of tolgee/testrail-api-client) exposes roughly the same tool surface, because they're all thin wrappers over the same five TestRail entity types:

  • Projects — get_projects, get_project — top-level containers. Most teams have one project per product; some split by squad.
  • Suites — get_suites, add_suite — a project can run in single-suite mode or multi-suite mode. This distinction trips up agents constantly (more below).
  • Sections — get_sections, add_section — folders within a suite, usually mirroring feature areas or epics.
  • Cases — get_cases, get_case, add_case, update_case — the actual test case: title, steps, expected result, priority, type, custom fields.
  • Runs — get_runs, add_run, close_run — a run is a snapshot of a subset of cases you intend to execute in one cycle (a sprint, a release candidate, a regression pass).
  • Results — add_result, add_result_for_case, get_results_for_run — the pass/fail/blocked outcome for a case within a specific run.

Here's what add_case looks like as a raw TestRail API payload — this is what the MCP tool sends under the hood when your agent calls it:

POST /index.php?/api/v2/add_case/{section_id}
{
  "title": "Login fails with locked account after 5 failed attempts",
  "template_id": 1,
  "type_id": 6,
  "priority_id": 3,
  "custom_steps_separated": [
    {
      "content": "Attempt login with valid username and wrong password 5 times",
      "expected": "Account is locked; error banner shows 'Account locked, try again in 15 minutes'"
    },
    {
      "content": "Attempt login with correct password while account is locked",
      "expected": "Login is rejected with the same lockout message, not 'invalid password'"
    }
  ],
  "refs": "JIRA-4521"
}

Two fields matter more than people expect: template_id determines whether TestRail renders this as a classic text case or a steps-separated case, and mismatching it against your project's configured templates is the single most common 400 error agents produce. refs is your link back to the requirement ticket — treat it as mandatory, not optional, because it's what makes traceability reports possible later.

Tips
- Run get_case_types and get_priorities once per project and cache the IDs in your MCP config or a project note — agents constantly guess priority_id: 1 for "High" when it's actually 4 in your instance.
- If your project uses multi-suite mode, every add_case call needs a section_id that belongs to the correct suite — an agent that doesn't call get_suites first will happily file cases into the wrong suite.
- get_cases supports filtering by type_id, priority_id, and updated_after — push agents toward these filters instead of pulling the entire case list and filtering client-side, which burns context fast on projects with 2,000+ cases.

TestRail MCP Authentication: API Key, Instance URL, and Project Scoping

TestRail MCP auth is deliberately boring, which is a feature. You need three things: your TestRail instance URL (https://yourcompany.testrail.io), a username (usually a service account email, not a personal one), and an API key generated from My Settings → API Keys in TestRail itself — not your login password. TestRail disabled password-based API auth by default starting with TestRail 7.3, so if you're on an older on-prem instance, check Administration → Site Settings → API to confirm API key auth is even enabled.

A typical MCP server config (this is the shape used by the testrail-mcp npm package, run via npx):

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@testrail/mcp-server"],
      "env": {
        "TESTRAIL_URL": "https://yourcompany.testrail.io",
        "TESTRAIL_USERNAME": "qa-bot@yourcompany.com",
        "TESTRAIL_API_KEY": "your-api-key-here",
        "TESTRAIL_PROJECT_ID": "14"
      }
    }
  }
}

TESTRAIL_PROJECT_ID is optional in most implementations but worth setting explicitly. Without it, every add_case or add_run call requires the agent to first resolve the project ID from a name, which is an extra round trip and an extra chance for it to pick the wrong project if your instance has similarly named ones ("Mobile App" vs "Mobile App - Legacy").

Never put the API key in a repo-committed .mcp.json. Use a .env file excluded via .gitignore, or your agent's secret-reference syntax if it supports one (Claude Code supports ${TESTRAIL_API_KEY} expansion from the shell environment in .mcp.json). I've seen a TestRail API key committed to a public mirror repo exactly once, and the fallout was a scramble to rotate it and audit three weeks of case history for unauthorized edits — TestRail's audit log does track this, but only if someone thinks to check.

Project scoping matters for a second reason beyond convenience: TestRail permissions are project-level. A service account with "restricted" access to Project A will get silent 403s if the agent tries to touch Project B, and most MCP wrappers surface that as a generic "request failed" — you'll want to check the raw HTTP status before assuming it's a bug in the agent's tool call rather than a permissions gap.

Tips
- Create a dedicated qa-bot TestRail user with a role scoped to exactly the projects your agents touch — don't reuse a human QA lead's API key, since key rotation then means breaking their personal workflows too.
- Store TESTRAIL_URL without a trailing slash — a stray slash is a surprisingly common source of 404 errors that look like auth failures.
- If you're on TestRail Cloud vs. self-hosted, double-check the API is reachable from your CI runners' network — self-hosted instances behind a VPN break agent-driven result posting from GitHub Actions unless you add a runner IP allowlist exception.

What AI Can Automate: Case Authoring, Run Creation, and Result Reporting

Three workflows are genuinely production-ready today, and one is still rough.

Case authoring from specs is the strongest use case. Feed an agent a Jira ticket or a markdown acceptance-criteria doc, and it can draft a full set of TestRail cases — positive path, negative path, edge cases, and often cases you didn't think to write (boundary values, concurrent-session conflicts, locale-specific formatting). The draft is not final; a human QA engineer still reviews before cases go into a suite that other testers rely on. Treat the agent's output as a first draft from a fast, occasionally overconfident junior tester.

Run creation from a case selection is close to fully automatable. "Create a run for the 2.14.0 release covering all P1 and P2 cases tagged checkout" is a query TestRail's API supports natively via add_run with a case_ids array, and an agent chaining get_cases (filtered) into add_run gets this right almost every time:

POST /index.php?/api/v2/add_run/{project_id}
{
  "suite_id": 12,
  "name": "Release 2.14.0 - Checkout Regression",
  "description": "Auto-generated run scoping P1/P2 checkout cases for release sign-off.",
  "include_all": false,
  "case_ids": [1042, 1043, 1050, 1051, 1067, 1071]
}

Result reporting from CI is the highest-leverage automation and the one most teams under-use. Instead of a human clicking through TestRail after every regression suite run, a CI job parses your test framework's JUnit XML or JSON report and posts results directly:

POST /index.php?/api/v2/add_result_for_case/{run_id}/{case_id}
{
  "status_id": 1,
  "comment": "Automated: Playwright suite, build #4821, 2.3s",
  "elapsed": "2s",
  "version": "2.14.0-rc3",
  "defects": ""
}

status_id values are TestRail defaults (1=Passed, 2=Blocked, 4=Retest, 5=Failed) unless your instance has custom statuses — check get_statuses before hardcoding, since I've seen instances with a 6th "Skipped" status that agents ignore and misreport as Passed.

What's still rough: fully autonomous triage of failures (deciding whether a failure is a real regression, a flaky test, or an environment issue) is not something I'd let an agent do unsupervised yet. It can summarize failure patterns well; it should not auto-close bugs or auto-mark cases as "not a defect" without a human sign-off.

Tips
- Have the agent draft cases into a staging section first (e.g., "Draft - Pending Review") rather than the live suite section — this gives QA leads a review gate without blocking the agent's throughput.
- For CI result posting, run the sync as a dedicated pipeline step immediately after the test job, using the build's own JUnit output as the source of truth — don't have the agent re-run tests to "check" before reporting.
- Cross-check status_id mappings against get_statuses per instance before wiring automated posting — the ID-to-meaning mapping is not guaranteed identical across TestRail installs.

Keeping Manual and Automated Test Data Consistent

The recurring failure mode with AI-assisted TestRail usage isn't bad case writing — it's data drift between what a human QA engineer expects a case to mean and what an automated result-posting script assumes it means. Three concrete disciplines prevent this.

First, a stable case-ID linking convention in automation code. Every automated test that maps to a TestRail case should reference that case ID in a comment or annotation, not just in a spreadsheet somewhere:

def test_checkout_declined_card_shows_retry_option():
    """
    TestRail: C1050
    Covers: Checkout Regression Suite / Payment Failures
    """
    ...

// checkout.spec.ts
test('declined card shows retry option', async ({ page }) => {
  // TestRail: C1050
  ...
});

This convention is what lets an agent (or a script) do coverage-gap analysis: pull all case IDs for a suite via get_cases, grep the automation codebase for TestRail: C\d+ annotations, and diff the two sets. Cases with no matching annotation are your automation gap; annotations with no matching live case are stale references from cases that got archived or merged.

Second, treat manual-only cases and automated cases as different lifecycles, not different tiers of quality. A common mistake is letting an agent auto-close manual cases as "covered by automation" the moment a Playwright test with a similar name exists. Verify the automated test actually asserts the same expected result as the manual case's custom_steps_separated, not just that the titles are similar — I've caught agents matching "Login with valid credentials succeeds" to an automated smoke test that only checks the page doesn't 500, missing the actual assertion on redirect destination.

Third, reconcile after every release cycle, not just when something breaks. A cheap, repeatable prompt pattern:

Pull all cases in suite 12 with priority P1 or P2 tagged "checkout."
Cross-reference against TestRail: C\d+ annotations in /tests/e2e/checkout/.
List: (a) cases with no automation reference, (b) automation references
pointing to case IDs that no longer exist in TestRail, (c) cases updated
in TestRail after their linked test was last modified in git.

That third bucket — cases updated after the linked test's last commit — catches the silent decay case: a QA lead edits acceptance criteria in TestRail, but nobody touches the corresponding Playwright spec. It's the single most valuable query in this whole workflow, and it's not something TestRail's own UI surfaces at all.

Tips
- Standardize the TestRail: C{id} comment format across every test framework in your stack (Playwright, Cypress, PyTest, JUnit) so a single grep pattern works everywhere.
- Run the coverage-gap reconciliation as a scheduled CI job (weekly is usually enough) rather than only on demand — drift compounds silently otherwise.
- When an agent proposes auto-closing a manual case as "covered," require it to quote the specific automated assertion it's matching against, not just the test name — this alone catches most false positives.

Tips

Tips
- Start with read-only TestRail MCP usage (querying cases, runs, coverage) for a few weeks before granting write access — it builds trust in what the agent gets right and wrong before it can mutate your system of record.
- Keep a human review gate on any agent-authored case before it enters a suite other testers execute against; treat AI drafts as fast first passes, not finished work.
- Cache static reference data (case types, priorities, statuses, templates) per project — refetching them on every agent turn wastes tokens and API calls for data that changes maybe twice a year.

Next TestRail MCP With Claude Code CLI and VS Code