Skip to main content
Glama
TestRail MCP Server

TestRail MCP Server

by trtmn

TestRail MCP Server

CI npm version License: MIT

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-mcp is now a Node/npm package, not a PyPI package. Use the install steps below; uv tool install tram-mcp / uvx tram-mcp no longer apply.

Requirements

  • Claude Code / the npx path: 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-mcp

That'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 (really npx.cmd) that way — the server fails to start (MCP error -32000). Wrap it in cmd /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 the testrail_login tool 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-mcp

Manage saved credentials anytime with npx tram-mcp status and npx tram-mcp logout.

Add to Claude Desktop

  1. Download tram-mcp.mcpb from the latest release.

  2. Open it (or Settings → Extensions → Install from file) and confirm the install.

  3. 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 (really npx.cmd) that way — the server fails to start. Wrap it in cmd /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

TESTRAIL_URL

Yes

Your TestRail instance URL (e.g. https://example.testrail.io)

TESTRAIL_USERNAME

Yes

TestRail username or email

TESTRAIL_API_KEY

Yes*

TestRail API key (recommended)

TESTRAIL_PASSWORD

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.js

Releasing

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 tools
browse_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 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.

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

    A3.7/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: browsing API categories, verifying auth, describing methods, executing commands, and searching test cases. No overlap or ambiguity.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables 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.
      18
      29 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Connects 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.
      20
      35 npm
      4
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Connect Claude, Cursor, and other AI assistants to your Testmo test management instance to manage test cases, folders, runs, milestones, and CI/CD automation.
      45
      2
      MIT