TestRail MCP server

A local stdio MCP server for the complete TestRail 10.7.0 API, powered by @dichovsky/testrail-api-client.

It exposes 133 tools, one per TestRail REST endpoint, across all 28 API resources, every one enabled by default, including writes, administration and deletes. It preserves TestRail's own field names and custom fields, pages lists with bounded fetch-all, uploads attachment and BDD files only from directories you configure, and saves downloaded attachments only to the directory you name. It targets Codex desktop and CLI, Claude Code and GitHub Copilot CLI. It covers TestRail's 10.7.0 API, and TestRail 10.8.1, the version its live qualification runs against, is the baseline; older versions are best effort.

Status

| Area | State | | --- | --- | | Endpoint tools | All 133 registered, each with a complete independent parameter manifest (coverage reports) | | Offline verification | Fixture contracts for every endpoint, both MCP protocol eras (legacy initialize and 2026-07-28), and the packed executable on Node 24 across Linux, macOS and Windows | | Client qualification | Closed by the owner on 2026-10-04: R02. Claude Code passed all 12 scenarios against the fixture stand-in (record). Codex CLI passed 10 of 12, as the owner reported. Codex desktop and Copilot CLI were not tested. Client configuration has the details | | Live TestRail 10.8.1 qualification and npm release | R03. The live run on 10.8.1 with the release's driver, 9.0.0, on 2026-10-04, has no failures: 98 tools pass, 27 are blocked by the instance's licence or the API user's permissions, and 8 were left out. Those 35 are documented limitations, not passes, and the changelog lists them. 1.0.0 is the first npm release; the placeholder before it, 0.0.0-bootstrap.0, is deprecated |

Install

Node 24 or later is required, and Node 24 is tested. The pinned driver, @dichovsky/testrail-api-client 9.0.0, requires Node 24 itself. Later majors satisfy the engine range but are untested and best effort.

Install an exact version from npm:

npm install --global @dichovsky/[email protected]
testrail-mcp --version

To try an unreleased change, install from a packed checkout. npm pack prints the tarball's file name; install that file by name, since Windows shells do not expand a * wildcard:

npm ci
npm pack
npm install --global ./dichovsky-testrail-mcp-<version>.tgz
testrail-mcp --version

Releases covers versioning, upgrading, rolling back and uninstalling.

Configure

The server reads its configuration from the environment of the process that launches it, usually the MCP client. It never reads a .env file, and never accepts credentials, hosts or URLs in tool arguments.

| Variable | Required | Meaning | | --- | --- | --- | | TESTRAIL_BASE_URL | Required | Your TestRail instance URL, such as https://example.testrail.io. Installation subpaths are kept. Embedded credentials, queries and fragments are refused. HTTPS unless TESTRAIL_ALLOW_INSECURE is true. | | TESTRAIL_EMAIL | Required | The TestRail user the server acts as. | | TESTRAIL_API_KEY | Required | That user's API key. It is never printed. | | TESTRAIL_MCP_UPLOAD_ROOTS | Required | A JSON array of existing absolute directories that upload tools may read from, such as ["/home/me/testrail-uploads"]. On Windows, JSON needs forward slashes or doubled backslashes: ["C:/Users/me/testrail-uploads"]. [] allows no uploads; the tools stay registered. | | TESTRAIL_MCP_DOWNLOAD_DIR | Required | An existing, writable absolute directory where downloaded attachments are kept. | | TESTRAIL_MCP_LIMITS | Optional | A strict JSON object overriding the limits below, such as {"max_all_items": 5000}. Unknown keys and out-of-range values stop startup. | | TESTRAIL_ALLOW_PRIVATE_HOSTS | Optional | true to reach an instance on a private or loopback network. Default false. | | TESTRAIL_ALLOW_INSECURE | Optional | true to allow plain HTTP. Default false. |

A missing or invalid value stops startup with a message naming the variable, never its value. TestRail's own permissions for the configured user still apply to every call.

Limits

| Key | Default | Highest allowed | | --- | --- | --- | | max_active_calls | 4 | 4 | | max_json_response_bytes | 10485760 (10 MiB) | 67108864 (64 MiB) | | max_file_bytes | 104857600 (100 MiB) | 104857600 (100 MiB) | | max_data_bytes | 1048576 (1 MiB) | 8388608 (8 MiB) | | max_result_bytes | 2621440 (2.5 MiB) | 25165824 (24 MiB) | | max_all_items | 1000 | 10000 | | max_all_pages | 20 | 100 | | max_all_bytes | 1048576 (1 MiB) | 8388608 (8 MiB) | | max_all_duration_ms | 45000 | 45000 |

max_all_bytes may not exceed max_data_bytes. Each TestRail request has its own 15-second request and body timeouts, and a request that passes either is reported as TIMEOUT. A call that gets no answer within 60 seconds is reported as TIMEOUT too, while its request finishes in the background.

Connect a client

Client configuration has examples for Codex desktop and CLI, Claude Code and GitHub Copilot CLI. Give the client a 120-second tool-call timeout, and keep every tool enabled: leave allow and deny filters unset, or, in Copilot CLI, set tools: ["*"] as its example does.

The client passes the variables under Configure to the server, so they must be in the environment the client itself was launched with, and node must be on that environment's path. A desktop app may not inherit what a terminal exports, so check how yours is launched.

How the tools behave

• Results. A result is {data}, with pagination on a paged list and warnings when there are any. data is TestRail's reply with its own field names, custom fields included. warnings flags fields that differ from the expected shape; the data is still passed through. See results and errors.
• Errors. Every error carries a fixed code, such as INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, RATE_LIMITED, TIMEOUT or PAGINATION_LIMIT. On a write, write_outcome says whether the change reached TestRail: not_started, acknowledged or unknown. Check before retrying an unknown write.
• Lists. 24 lists are paged. 18 of them return one page of 50 by default, and up to 250 on request. On any of the 24, set _mcp.pagination to "all" for a bounded complete fetch, as far as TestRail's replies link on. It stops with PAGINATION_LIMIT, and no partial data, if it would pass a bound. Other lists, such as testrail_get_statuses and testrail_get_users, return TestRail's whole reply and take no _mcp settings.
  • Six lists choose their own pages and take no page size or offset: testrail_get_variables, testrail_get_datasets, testrail_get_shared_step_history, testrail_get_roles, testrail_get_groups and testrail_get_case_statuses.
  • Their later pages are reachable only through "all".
  • See pagination.
• Network. By default the server connects to TestRail directly, to the address the driver's DNS check approved. Proxy settings (HTTP_PROXY, HTTPS_PROXY, NODE_USE_ENV_PROXY) are not used, so an instance reachable only through a proxy cannot be used that way. With TESTRAIL_ALLOW_PRIVATE_HOSTS set to true, the driver skips that check and the pinning, and Node's own connection settings apply, a configured proxy included, which then carries the credential. For a private certificate authority, set NODE_EXTRA_CA_CERTS before starting the server. DNS resolution counts against each request's 15-second timeout. See startup configuration.
• Files. Uploads read a local path that must resolve inside an upload root. The server sends a copy it makes in a private directory under the system's temporary directory (on Windows, only as private as that temporary directory), and removes the copy once the request has settled. Each download writes a new file to the download directory and never overwrites one, so its tools are marked as not read-only. The server never deletes a completed download. See local files.
• Side effects. Every tool carries MCP annotations describing its effect. Report runs generate a report, and may send the template's configured email, so don't call them repeatedly. The server adds no confirmation step of its own; your client's approval settings apply.
• Cancellation. Cancelling a call stops the server waiting for it, and the client gets no result for that call. A request already sent to TestRail may still complete, so treat a cancelled write as possibly applied and check before retrying it. One exception comes from the MCP SDK: on a 2026-07-28 connection, cancelling the first ordinary request, whose id is 0, is ignored, and that call completes and answers normally. See runtime lifetime and stdio transport.

Development

npm ci
npm run check

npm run check runs these steps, and none of them need TestRail credentials:

1. builds from a clean output directory, after checking that each direct dependency is installed at the version package-lock.json records. If one is not, for example after a pull that changed a pin, the build stops and names it; run npm ci;
2. checks the registry against the pinned operation inventory and the generated operation reference;
3. typechecks and lints;
4. runs every test;
5. packs and installs the tarball into a clean directory, then drives the installed executable over MCP in both protocol eras against a local stand-in for TestRail.

CI runs these steps on Node 24 across Linux, macOS and Windows. On Linux its test step is npm run test:coverage instead, which runs the same tests and fails if source coverage of src/ drops below 99% for lines, statements, functions or branches; the thresholds live in vitest.config.ts. CI also publishes the coverage reports as artifacts. Source layout follows the component boundaries.

Documents

• Implementation plan and GitHub work items, architecture and implementation contracts
• Endpoint coverage, machine-readable inventory, operation reference and coverage reports
• Registry authoring and parameter fixtures
• Startup configuration, runtime lifetime, results and errors, pagination, local files and stdio transport
• Driver qualification and client configuration and verification
• Releases and compatibility policy, changelog and live TestRail qualification
• Domain glossary, design decision and research sources