testrail-mcp

An MCP server that lets Claude upload test cases to TestRail.

You describe the feature to Claude in a chat; Claude writes the test cases there. This server's only job is to talk to TestRail: find the right section, check required fields, and create the cases (with step-by-step actions and expected results). No user-story form, no screenshot area, no AI key — the chat is the interface.

• Python, one dependency (mcp); HTTP calls use the standard library.

• Your TestRail URL, email and API key are read only from environment variables set in your MCP client's config. Nothing personal is stored in this repository.

Tools

testrail_add_cases and testrail_upload_case_file accept dry_run: true to preview exactly what would be sent without creating anything. Dropdown fields accept the option label (e.g. "Not Automated") or its numeric id.

Related MCP server: QA Studio MCP Server

Install

Requires Python 3.10+ and uv (or plain pip).

git clone https://github.com/<your-github-user>/testrail-mcp.git
cd testrail-mcp
uv sync            # or: pip install -e .

Connect it to Claude Desktop

Open Settings → Developer → Edit Config in Claude Desktop and add a server entry (full example: examples/claude_desktop_config.json):

{
  "mcpServers": {
    "testrail": {
      "command": "uv",
      "args": ["--directory", "C:\\path\\to\\testrail-mcp", "run", "testrail-mcp"],
      "env": {
        "TESTRAIL_URL": "https://yourcompany.testrail.io",
        "TESTRAIL_USER": "you@company.com",
        "TESTRAIL_API_KEY": "your-api-key",
        "TESTRAIL_PROJECT_ID": "1"
      }
    }
  }
}

Restart Claude Desktop. The tools then appear in your chats.

The config file lives only on your computer, so your key never goes into git. Use a TestRail API key (TestRail → My Settings → API Keys), not your password, so you can revoke it any time.

Settings

If TestRail says a field "is a required field", ask Claude to run testrail_get_fields and then either pass the value per upload or put it in TESTRAIL_DEFAULT_FIELDS.

Using it

Example prompts:

Write test cases for the CSV export story below, then add them to the "Reports > Export" section with refs PROJ-123.

Upload C:\Users\me\Downloads\export-cases.json to section 42.

Claude will look up the section, check required fields, show you the cases, and create them. Each result links to the new case in TestRail.

Case-pack file format

testrail_upload_case_file reads this JSON shape (images are optional and embedded as base64):

{
  "format": "testrail-case-pack",
  "version": 1,
  "refs": "PROJ-123",
  "section_id": null,
  "fields": {"custom_automation_type": "Not Automated"},
  "image_placement": "expected",
  "notes": ["anything to double-check before uploading"],
  "cases": [
    {
      "title": "Verify CSV export downloads a file",
      "preconditions": "User is signed in",
      "steps": [
        {"content": "Open Reports and click Export CSV", "expected": "A .csv file downloads", "images": ["img1"]}
      ]
    }
  ],
  "images": {"img1": {"name": "export.png", "mime": "image/png", "data": "<base64>"}}
}

section_id and fields in the call override the file; the file overrides the environment defaults.

Development

uv sync --extra dev
uv run pytest

Tests run against an in-memory fake TestRail (tests/fake_testrail.py), so they never touch a real instance.

License

MIT