TestRail MCP Server
The TestRail MCP Server connects Claude (or other MCP clients) to TestRail, enabling natural language interaction to browse the API, search test cases, and manage runs and results.
Verify Authentication (
check_testrail_auth): Confirm that your TestRail credentials are correctly configured, with structured diagnostic feedback and error hints.Browse the TestRail API (
browse_testrail_api): Explore all available TestRail API categories and their methods to discover what operations are available.Describe API Methods (
describe_testrail_method): Get detailed documentation for any specific TestRail API method, including parameters, types, and usage notes.Search Test Cases (
search_test_cases): Search for test cases by title using a case-insensitive substring match within a specific project, optionally filtered by suite.Execute Any TestRail API Command (
run_testrail_command): Run any TestRail API method (e.g., get projects, add cases, manage runs, record results) with support for optional field filtering, result truncation, and extra query parameters.
Enables AI assistants to manage test cases, test runs, test results, and other TestRail entities through the TestRail API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@TestRail MCP Server get test runs for project ID 5"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
TestRail MCP Server
Connect Claude to TestRail — browse the API, search test cases, and manage runs and results through natural language. Built on the Model Context Protocol.
tram-mcp runs locally over stdio — your MCP client spawns it as a child
process. It's distributed as the npm package
tram-mcp and as a Claude Desktop
.mcpb bundle.
Migrating from the old Python package?
tram-mcpis now a Node/npm package, not a PyPI package. Use the install steps below;uv tool install tram-mcp/uvx tram-mcpno longer apply.
Requirements
Claude Code / the
npxpath: Node.js ≥ 18.Claude Desktop
.mcpb: nothing — Desktop bundles its own Node runtime.
Related MCP server: TestCollab MCP Server
Add to Claude Code
Register the server (a coworker — or Claude Code itself — can run this verbatim):
claude mcp add tram-mcp -- npx -y tram-mcpThat's it — Claude Code spawns npx -y tram-mcp over stdio. Start a session and run
/mcp; you should see tram-mcp with its tools.
Windows: the client spawns the command without a shell, and Windows can't execute
npx(reallynpx.cmd) that way — the server fails to start (MCP error -32000). Wrap it incmd /c:claude mcp add tram-mcp -- cmd /c npx -y tram-mcp
Logging in — no terminal needed. The first time you ask Claude to do anything in
TestRail without credentials configured, it calls the testrail_login tool, which
opens a browser form. Enter your TestRail URL, username, and API key (My
Settings → API Keys in TestRail), submit, and retry your request — the server picks up the
new credentials on the next call, no restart required. They're validated against TestRail
and saved to ~/.tram-mcp/credentials.json (readable only by you). You can trigger it
anytime by asking Claude to "log in to TestRail."
Prefer the terminal? Run npx tram-mcp login for the same browser form before starting
Claude (see Configuration for the env-var alternative).
Prefer to hand it to Claude Code as a prompt? Paste this:
Add the TestRail MCP server: run
claude mcp add tram-mcp -- npx -y tram-mcp, then use thetestrail_logintool so I can enter my TestRail credentials in the browser.
Prefer environment variables (CI, or to skip the browser form)? Set TESTRAIL_URL,
TESTRAIL_USERNAME, and TESTRAIL_API_KEY (or TESTRAIL_PASSWORD) — they take precedence
over the saved file. You can pass them inline when adding the server:
claude mcp add tram-mcp \
-e TESTRAIL_URL=https://yourinstance.testrail.io \
-e TESTRAIL_USERNAME=you@example.com \
-e TESTRAIL_API_KEY=your-api-key \
-- npx -y tram-mcpManage saved credentials anytime with npx tram-mcp status and npx tram-mcp logout.
Add to Claude Desktop
Download
tram-mcp.mcpbfrom the latest release.Open it (or Settings → Extensions → Install from file) and confirm the install.
Fill in your TestRail URL, username, and API key in the form. The API key is stored in your OS keychain. Done — no terminal, no config editing.
Other clients (Cursor, VS Code, …)
Any MCP client that runs a stdio command works. Use npx -y tram-mcp as the command and
supply credentials via the TESTRAIL_* env vars, e.g. ~/.cursor/mcp.json:
{
"mcpServers": {
"tram-mcp": {
"command": "npx",
"args": ["-y", "tram-mcp"],
"env": {
"TESTRAIL_URL": "https://yourinstance.testrail.io",
"TESTRAIL_USERNAME": "you@example.com",
"TESTRAIL_API_KEY": "your-api-key"
}
}
}
}Windows: many MCP clients spawn the command without a shell, and Windows can't execute
npx(reallynpx.cmd) that way — the server fails to start. Wrap it incmd /c:{ "mcpServers": { "tram-mcp": { "command": "cmd", "args": ["/c", "npx", "-y", "tram-mcp"] } } }
Configuration
Credentials come from the in-session testrail_login tool or npx tram-mcp login (both
save to ~/.tram-mcp/), the Desktop install form, or these environment variables (which
take precedence):
Variable | Required | Description |
| Yes | Your TestRail instance URL (e.g. |
| Yes | TestRail username or email |
| Yes* | TestRail API key (recommended) |
| Yes* | TestRail password (alternative to API key) |
*Either TESTRAIL_API_KEY or TESTRAIL_PASSWORD must be set.
Development
TypeScript; source in src/, tests in test/.
npm install
npm run check # tsc --noEmit
npm test # vitest
npm run build:cli # bundle the CLI -> dist/cli.jsReleasing
Automated by release-please. Merge a PR into development with a
Conventional Commit title; release-please opens a
Release PR that bumps the version. Merging that Release PR tags the release, publishes to
npm, and attaches the tram-mcp.mcpb to the GitHub Release. See CLAUDE.md for details.
License
MIT
Available Tools
5 toolsbrowse_testrail_apiA
Browse all available TestRail API categories and their methods.
Returns a dict mapping each category name to its description and list of available method names. Use describe_testrail_method() to get details for a specific method, then run_testrail_command() to call it.
Inputs: no named parameters. Returns: object
check_testrail_authA
Verify the configured TestRail credentials and report a structured diagnosis.
Calls a lightweight TestRail endpoint (get_priorities, which every
authenticated user can reach) and translates the outcome into an
actionable result the LLM can act on. Use this when:
A user reports the server isn't working
Another tool returns a 401/403/auth error and the cause is unclear
Confirming setup is correct before kicking off a longer workflow
Returns a dict with at least:
ok: bool — True if the credential check succeededconfig: which URL / username / auth method the server is using (never includes the secret itself)
On success, also includes the priorities count and the username TestRail
associates with the credentials. On failure, includes error_class,
error, status_code (when extractable), and a human-readable
hint explaining the most likely cause and remediation.
Inputs: no named parameters. Returns: object
describe_testrail_methodB
Describe a specific TestRail API method — its parameters, types, and docs.
Inputs: category (required), method (required). Returns: object
run_testrail_commandC
Execute a TestRail API method.
Inputs: category (required), method (required), params, extra_params, +2 more. Returns: result
search_test_casesA
Search for test cases by title (case-insensitive substring match).
Inputs: project_id (required), query (required), suite_id. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose: browsing API categories, verifying auth, describing methods, executing commands, and searching test cases. No overlap or ambiguity.
All tool names follow a consistent verb_noun pattern using snake_case. The prefix `testrail` is used uniformly where applicable, and `search_test_cases` follows the same convention.
With 5 tools, the count is slightly low for a full TestRail integration, but the generic API runner covers many operations. The set feels appropriately scoped for a minimal yet functional server.
While dedicated tools for common operations are missing, the `run_testrail_command` combined with `browse_testrail_api` and `describe_testrail_method` allow execution of any TestRail API method, making the surface complete in practice.
Maintenance
Related MCP Connectors
Create and manage test cases, test runs and results in Testiny from your AI assistant.
Direct access to Cypress tests results and accessibility reports in your AI workflow.
Approved test intent, reviewed Playwright automation and run evidence, inside your editor.
Add any agent you deploy on ibl.ai to Claude Code, Cursor or Claude Desktop and talk to it there.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to interact with TestRail test management systems through comprehensive API integration. Supports retrieving and updating test cases, projects, suites, runs, and results, plus adding attachments and managing test data through natural language commands.1829 npmMIT
- AlicenseAqualityBmaintenanceConnects AI coding assistants to TestCollab for managing test cases, plans, and suites directly through natural language. It enables users to create, update, and query testing resources within integrated development environments and AI chat clients.2035 npm4MIT
- AlicenseBqualityDmaintenanceConnect Claude, Cursor, and other AI assistants to your Testmo test management instance to manage test cases, folders, runs, milestones, and CI/CD automation.452MIT
- AlicenseBqualityDmaintenanceIntegrates TestRail with Claude Code to enable AI-assisted test management workflows, including project, suite, test case, test run, and result operations.13327 npmMIT