tram-mcp 0.3.0

MCP server exposing TestRail API endpoints as tools for LLMs

TestRail MCP Server

Connect your AI coding assistant to TestRail — manage test cases, runs, results, and more directly from VS Code, Cursor, Claude Desktop, or Claude Code. Built on the Model Context Protocol and powered by testrail_api_module.

Features

• Dynamic tool discovery — endpoints are introspected from testrail_api_module at startup, so new API coverage is picked up automatically
• LLM-friendly — instead of registering hundreds of tools, provides a category-based discovery pattern so models can explore available operations without being overwhelmed

Requirements

• Python 3.11+
• uv

Quick Install

After installing, you will be prompted to fill in your TestRail credentials. See Configuration below.

Manual Installation

Claude Desktop

Add to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "testrail": {
      "command": "uvx",
      "args": ["tram-mcp"],
      "env": {
        "TESTRAIL_URL": "https://yourinstance.testrail.io",
        "TESTRAIL_USERNAME": "[e-mail]",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

claude mcp add testrail \
  -e TESTRAIL_URL=https://yourinstance.testrail.io \
  -e TESTRAIL_USERNAME=[e-mail] \
  -e TESTRAIL_API_KEY=your-api-key \
  -- uvx tram-mcp

VS Code / VS Code Insiders

Create .vscode/mcp.json in your project (or add to your User Settings):

{
  "servers": {
    "testrail": {
      "type": "stdio",
      "command": "uvx",
      "args": ["tram-mcp"],
      "env": {
        "TESTRAIL_URL": "",
        "TESTRAIL_USERNAME": "",
        "TESTRAIL_API_KEY": ""
      }
    }
  }
}

VS Code supports ${input:variableName} placeholders to prompt for values at startup.

Cursor

Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "testrail": {
      "command": "uvx",
      "args": ["tram-mcp"],
      "env": {
        "TESTRAIL_URL": "https://yourinstance.testrail.io",
        "TESTRAIL_USERNAME": "[e-mail]",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

Configuration

The server requires TestRail credentials via environment variables:

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
TESTRAIL_PASSWORD	Yes*	TestRail password (alternative to API key)

*Either TESTRAIL_API_KEY or TESTRAIL_PASSWORD must be set. API key is recommended.

Development

# Install dependencies
uv sync

# Run the server locally
uv run tram_mcp

# Run tests
uv run pytest

# Run a single test
uv run pytest path/to/test.py::test_name -v

Releasing

Merging a PR to main automatically tags the version and publishes to PyPI. You must bump the version before merging:

uv version 0.2.0  # update version in pyproject.toml

If you forget to bump, the publish will be skipped (the existing version tag already exists on PyPI).

License

MIT