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.
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.
Claude Code / the npx path: Node.js ≥ 18.
Claude Desktop .mcpb: nothing — Desktop bundles its own Node runtime.
Related MCP server: TestRail MCP Server
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.
Download tram-mcp.mcpb from 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.
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"] } } }
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.
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.jsAutomated 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.
MIT
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description adequately indicates read-only browsing behavior and return type. Could mention network or rate limits, but sufficient for a browse operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct sentences, front-loaded with purpose, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and output schema implied, description fully covers what the tool does and its output structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters in schema, baseline 4. Description adds no param info, but none needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it browses all TestRail API categories and methods, specifies return format, and distinguishes from siblings by directing to describe_testrail_method for details and run_testrail_command for execution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes when to use this tool (to browse categories) and guides to subsequent tools for deeper details and execution, providing a clear workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 succeeded
config: 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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It details the lightweight call (get_priorities), the return dict structure with ok, config, success/failure fields, and even includes error_class and hints. Fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with clear sections and bullet points. Slightly verbose but not overly so; every sentence adds value. Could be trimmed, but still effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and an output schema (though not provided in input, description explains it), the description is complete. It covers purpose, usage, behavior, and return values thoroughly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has zero parameters. According to guidelines, baseline is 4. The description does not need to add parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states it verifies TestRail credentials and provides a structured diagnosis. The verb 'Verify' and resource 'TestRail credentials' are specific. It clearly distinguishes itself from sibling tools like run_testrail_command or search_test_cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Lists explicit scenarios when to use: user reports server issues, auth errors from other tools, or before longer workflows. Lacks explicit when-not-to-use, but the context is clear and sufficient for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Describe a specific TestRail API method — its parameters, types, and docs.
| Name | Required | Description | Default |
|---|---|---|---|
| category | Yes | The API category (e.g. "projects", "cases", "runs"). | |
| method | Yes | The method name (e.g. "get_projects", "add_case"). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description implies a read-only operation ('Describe'), which is accurate. However, it does not disclose any other behavioral traits such as authentication needs, rate limits, or output format. Given no annotations, the description does a minimal job but could add more context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loads the key information. It avoids unnecessary words, though it could benefit from slightly more structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description does not need to explain return values. However, it does not mention that the method name should be exact or that the output includes detailed documentation. Overall, it is minimally adequate but leaves some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear descriptions for both parameters. The tool description does not add any additional meaning beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it describes a specific TestRail API method with parameters, types, and docs. It is specific about the resource and action, though it does not explicitly distinguish from the sibling tool 'browse_testrail_api' which might browse a list of methods rather than describe one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'browse_testrail_api' or 'run_testrail_command'. There is no explanation of when not to use it or what prerequisites exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a TestRail API method.
| Name | Required | Description | Default |
|---|---|---|---|
| category | Yes | The API category (e.g. "projects", "cases", "runs"). | |
| method | Yes | The method name (e.g. "get_projects", "add_case"). | |
| params | No | Optional dict of parameters to pass to the method. | |
| extra_params | No | Optional dict of additional query parameters that are appended to the API request URL. Use this for filters not directly supported by the method signature, such as custom field filters (e.g. ``{"custom_automation_type": "1"}``). These are merged into the URL query string alongside the method's own parameters. | |
| fields | No | Optional list of field names to include in each result item. When provided and the response is a list of dicts, each dict is filtered to only contain the specified keys. Useful for reducing response size (e.g. ``fields=["id", "title"]``). | |
| max_results | No | Optional maximum number of items to return. When provided and the response is a list longer than this value, the list is truncated and the return value becomes a dict with ``results`` (the truncated list), ``truncated`` (True), ``total_count`` (original length), and a human-readable ``message``. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral traits, but it only states 'Execute a TestRail API method.' It does not disclose read/write nature, authentication needs, error behaviors, or side effects like pagination truncation (implied by 'max_results' parameter).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence) but at the expense of informativeness. It does not earn its place because it provides minimal value; more context is needed for a tool with six parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, output schema), the description is incomplete. It does not explain the return structure (though output schema exists), side effects, or how 'execute' relates to the TestRail API. The sibling tools offer context but the description should be self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds no parameter information beyond the schema; it simply repeats the verb. The schema already documents each parameter adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Execute a TestRail API method' clearly states the tool's action (execute) and resource (TestRail API method). It distinguishes from siblings like 'describe_testrail_method' (which describes rather than executes) and 'search_test_cases' (which searches), though it lacks specificity about what methods are supported.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives. The description does not mention prerequisites, when not to use it, or suggest siblings like 'describe_testrail_method' for method details. An agent must infer usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for test cases by title (case-insensitive substring match).
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The ID of the project to search in. | |
| query | Yes | The search string to match against case titles. | |
| suite_id | No | Optional suite ID to narrow the search. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden. It reveals the matching behavior (case-insensitive substring) but does not mention side effects, required permissions, or output structure. Adequate for a read-only search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler. It is front-loaded with the verb and object, and every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values need not be explained. The description covers the primary search behavior but could clarify that the search is scoped to a project with optional suite narrowing. Still, it is largely complete for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so baseline is 3. The description adds value by specifying the match as 'case-insensitive substring', clarifying the query parameter's behavior beyond its schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for test cases by title with case-insensitive substring matching. The verb 'search' and resource 'test cases' are specific, distinguishing it from sibling tools like browse_testrail_api or run_testrail_command.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives or when not to use it. The description simply states what it does without context about exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.6.0browse_testrail_apicheck_testrail_authdescribe_testrail_methodrun_testrail_commandsearch_test_casesScored 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.
Direct access to Cypress tests results and accessibility reports in your AI workflow.
Run, debug, and triage tests from your IDE using natural language, no dashboard switching, no manual data transfers. The TestMu AI (formerly LambdaTest) MCP Server is a single remote server exposing four tool suites: HyperExecute — analyze your project, generate YAML configs and test runner commands, then monitor jobs and sessions. Automation — pull a TestID's details plus command, network, and console logs into one chat for instant root-cause analysis. Includes mobile app upload. SmartUI — explain pixel, layout, DOM, and perceptual changes in a visual regression run, with context-aware React/HTML/CSS fixes. Accessibility — audit any public URL or a local React app against WCAG and get ready-to-apply remediation steps. Connects over https://mcp.lambdatest.com/mcp using OAuth 2.1 — no API keys in your config. One-click install in Cursor; works with Claude, GitHub Copilot, Cline, and any MCP client. Tests execute on the TestMu AI cloud: 3,000+ browsers and 10,000+ real devices.
Connect your team's living knowledge base — docs, data, issues, CRM — to Claude and ChatGPT.
Manage test suites, run tests, view results, and automate QA workflows via AI with testRigor.
