testrail-mcp

An MCP server for TestRail that goes beyond CRUD: it prepares everything an MCP client needs to generate real test cases from Jira tickets, Confluence pages, or any free-form spec — and pushes them back to TestRail.

Built on the official Python MCP SDK (FastMCP). Designed to plug into Claude Desktop, Claude Code, Cursor, or any other MCP-capable client.

No ANTHROPIC_API_KEY required. The server never calls an LLM. It fetches data (Jira/Confluence/TestRail), bundles in house-style anchors, and returns it with instructions for your MCP client. The LLM work happens in your client (Claude Desktop / Cursor / etc.) on your existing subscription — you pay once.

What it gives you

CRUD over TestRail

• list_projects — projects visible to the user
• list_suites — suites under a project
• search_test_cases — list cases under a project / suite / section, optionally filter by title substring
• get_test_case — fetch one case by ID
• create_test_case — create a case in a section
• get_or_create_section — resolve a path like Auth > Login > Edge Cases, creating missing nodes

Preparation tools — fetch + bundle data, hand off to your MCP client's LLM

• prepare_cases_from_text — feed any spec/PRD/bug-report text → returns spec + house-style anchors + schema + instructions for the client to generate cases.
• prepare_cases_from_jira — pass a Jira issue key (e.g. ABC-123); server fetches summary, description, comments, subtasks, walks the ADF tree.
• prepare_cases_from_confluence — pass a Confluence page ID; HTML body stripped to plain text.
• preview_house_style — see the 5 sibling cases the server will use as in-context style anchors.
• add_test_cases_bulk — once the LLM has the cases array, push them all into TestRail in one call (with auto section-hierarchy creation).

All three prepare_cases_* tools pull a few existing cases from the target section as house-style examples by default, so generated cases match local title casing, step granularity, and expected-result phrasing. Override with house_style_section_id to draw style from a different "golden" section, or set house_style=False to skip.

Quick start

Run with uvx (recommended — no clone, no venv)

Once the package is on PyPI:

uvx testrail-mcp-server

For local development from a checkout:

git clone https://github.com/Sergey-Bl/testrail-mcp
cd testrail-mcp
uv venv --python 3.12
uv pip install -e .
cp .env.example .env   # fill in TestRail / Jira / Anthropic keys

Inspect interactively (recommended first step)

npx @modelcontextprotocol/inspector python server.py

This opens a local web UI where each tool can be called by hand. Use it to verify auth and tool wiring before you plug into a client.

Use in Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "testrail": {
      "command": "uvx",
      "args": ["testrail-mcp-server"],
      "env": {
        "TESTRAIL_BASE_URL": "https://your-org.testrail.io",
        "TESTRAIL_USER": "you@example.com",
        "TESTRAIL_API_KEY": "...",
        "TESTRAIL_PROJECT_ID": "1",
        "TESTRAIL_SUITE_ID": "1",
        "JIRA_BASE_URL": "https://your-org.atlassian.net",
        "JIRA_USER": "you@example.com",
        "JIRA_API_TOKEN": "..."
      }
    }
  }
}

Restart Claude Desktop. The testrail server should appear in the tools menu.

Use in Claude Code

claude mcp add testrail -- uvx testrail-mcp-server

(You'll still need to provide env vars — either via claude mcp add --env KEY=VALUE flags or a .env in the working directory.)

Use in Cursor

In ~/.cursor/mcp.json:

{
  "mcpServers": {
    "testrail": {
      "command": "uvx",
      "args": ["testrail-mcp-server"],
      "env": { "TESTRAIL_BASE_URL": "...", "TESTRAIL_USER": "...", "TESTRAIL_API_KEY": "..." }
    }
  }
}

Configuration

Env var	Required	Purpose
TESTRAIL_BASE_URL	yes	e.g. https://your-org.testrail.io
TESTRAIL_USER	yes	TestRail account email
TESTRAIL_API_KEY	yes	from My Settings → API Keys
TESTRAIL_PROJECT_ID	optional	default project ID for tools that take it
TESTRAIL_SUITE_ID	optional	default suite ID
TR_TEMPLATE_ID	optional	default template (2 = "Test Case (Steps)")
TR_TYPE_ID	optional	default case type
TR_PRIORITY_ID	optional	default priority (3 = Medium)
JIRA_BASE_URL	optional	only for prepare_cases_from_jira
JIRA_USER	optional	Jira account email
JIRA_API_TOKEN	optional	https://id.atlassian.com/manage-profile
CONFLUENCE_BASE_URL	optional	only for prepare_cases_from_confluence
CONFLUENCE_EMAIL	optional	defaults to JIRA_USER
CONFLUENCE_API_TOKEN	optional	defaults to JIRA_API_TOKEN

Example: from a Jira ticket straight into TestRail

In Claude Code or Claude Desktop, after the server is registered:

Generate test cases from ABC-123 and put them under Auth > Login > Smoke.

The server walks the section path (creating missing nodes), pulls the Jira ticket, generates ~15-30 cases, then bulk-creates them with house-style defaults (template 2, type 7, priority 3). Reply contains every new case ID.

Tool reference

In addition to the basics above:

Test-case authoring & QA

• prepare_feature_bootstrap — one-shot: ingest a Confluence page / Jira ticket / raw spec, plan the suite + section, fetch house-style anchors. Hand it all back to the client LLM with step-by-step instructions for generation + push.
• dedupe_against_section — flag generated cases that look like duplicates of cases already in a target section (title-token containment; configurable threshold).
• prepare_lint — return the case batch + lint instructions; the client LLM reviews and reports vague titles, generic expecteds, combined steps, etc.
• prepare_coverage_gaps — return the spec + case titles + instructions; the client LLM lists testable behaviours not covered.
• list_sections, find_populated_section, create_suite, update_case — CRUD helpers.

Test-run management & reporting

• list_runs, get_run, get_tests_in_run, get_results_for_run — read-side access.
• create_run, update_run, close_run — write-side. Pair with CI to auto-create a run per build.
• add_result, add_bulk_results — post results back from automation. Status accepts either a string ("passed", "failed", "blocked", "retest") or a TestRail status_id.
• prepare_run_summary — fetch run metadata + statuses + failure comments; client LLM writes the ship-ready Markdown report.
• prepare_runs_diff(run_a, run_b) — regression/fix delta between two runs; client LLM narrates the diff as Markdown.
• flaky_test_detector(case_id, last_n_runs) — pull a case's status across recent runs and flag flakiness when it flips between pass/fail. Pure data, no LLM needed.

Roadmap

• [ ] SSE / HTTP transport for hosted use
• [ ] Embedding-based dedupe (semantic, not just token overlap)
• [ ] update_case — patch existing cases when the spec changes
• [ ] Suite cloning across projects

License

MIT