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

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 [email protected] \
  -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": "[email protected]",
        "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