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

Run these two commands (a coworker — or Claude Code itself — can follow them verbatim):

claude mcp add tram-mcp -- npx -y tram-mcp
npx tram-mcp login

1. The first command registers the server (Claude Code spawns npx -y tram-mcp over stdio).
2. npx tram-mcp login opens a browser form — enter your TestRail URL, username, and API key (My Settings → API Keys in TestRail). Credentials are validated against TestRail and saved to ~/.tram-mcp/credentials.json (readable only by you).

Then start a Claude Code session and run /mcp — you should see tram-mcp with its tools.

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 run npx tram-mcp login 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"
      }
    }
  }
}

Configuration

Credentials come from npx tram-mcp login (saved 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