tuskr-mcp-server

Implements a Model Context Protocol (MCP) server for the Tuskr REST API

Built on the FastMCP Python SDK.
Supports access token authentication.

Tools

Every tool wraps a single Tuskr REST endpoint, relative to https://api.tuskr.live/api/tenant/<tenant-id>/.

Result status keys such as PASSED and FAILED are configured per tenant, so use the keys defined in your own account.

add_test_run_results matches a test run given by key or name across the whole tenant, not within one project. When several projects have a run with the same key, for example R-1, Tuskr rejects the call with Multiple test runs found matching: R-1 and records nothing. Pass the run's UUID instead; list_test_runs returns it for a given project.

Tuskr rate-limits every plan at 10 requests/second. The bulk tools exist for that reason: batch where the endpoint allows it.

Attachments

add_test_run_results accepts an attachments list of local file paths, for screenshots and logs. Tuskr allows two files of 5 MB each per call and attaches every file to the result record of every test case in that call, so record cases that need different evidence in separate calls. Both limits are checked before the request is sent.

Attachments are off by default. The tool arguments are chosen by the model, so a plain path would let a prompt injection upload any file the server can read. Set TUSKR_ATTACHMENT_DIR to the one directory the server may read from. Relative paths resolve against it, and anything that resolves outside it, including through a symlink, is rejected. Because the server reads the files itself, this only works when the server runs on the machine that holds them (stdio, or an HTTP instance with the directory mounted).

The server also exposes one resource, resource://service_description, which describes its purpose to the client.

Installation

Environment variables / .env file

Set up environment variables or configure the .env file using the .env.example template.

The following environment variables are supported:

TUSKR_TENANT_ID=<your tenant id>
TUSKR_ACCESS_TOKEN=<your access token>

(this doc desc https://tuskr.app/kb/latest/api)

and optionally

MCP_TRANSPORT=<transport type: http or stdio>
MCP_HOST=<host for HTTP transport>
MCP_PORT=<port for HTTP transport>
TUSKR_ATTACHMENT_DIR=<directory attachments may be read from>

Command Line Parameters

The MCP server supports the following command line parameters:

• --transport: Transport type for the MCP server. Options: http (default) or stdio
• --host: Host address for HTTP transport (default: 0.0.0.0)
• --port: Port number for HTTP transport (default: 8000)

Note: The --host and --port parameters are only applicable when using the http transport.

Default Values

• Transport: http (can be overridden with MCP_TRANSPORT environment variable)
• Host: 0.0.0.0 (can be overridden with MCP_HOST environment variable)
• Port: 8000 (can be overridden with MCP_PORT environment variable)

Connect from client

HTTP Transport (Default)

Use the following template to connect the server via HTTP:

{
  "mcpServers": {
    "tuskr": {
      "transport": "http",
      "url": "http://<your-mcp-dns-or-ip>/mcp/",
      "headers": {
        "Authorization": "Bearer <your access token>",
        "Tenant-ID": "<your-tuskr-tenant-id>"
      }
    }
  }
}

The Authorization is mandatory.

The Tenant-ID is not required and can be set on the server side using the TUSKR_TENANT_ID env variable. It's convenient in case you have a single MCP Server for your organization.

Migrating from TUSKR_ACCOUNT_ID

Earlier versions of this server used the env var TUSKR_ACCOUNT_ID and the HTTP header Account-ID. These continue to work, but emit a deprecation warning. Tuskr's own documentation and UI consistently use the term "Tenant ID" (it is part of the REST URL path: /api/tenant/<tenant-id>/), so the preferred names are now TUSKR_TENANT_ID and the Tenant-ID HTTP header. Both names will be supported until a future major version removes the legacy names.

To migrate an existing config, replace TUSKR_ACCOUNT_ID with TUSKR_TENANT_ID; no other changes are required.

stdio Transport (for local development)

For local development and integration with tools like uvx, use the stdio transport:

{
  "mcpServers": {
    "tuskr": {
      "transport": "stdio",
      "command": "uvx",
      "args": ["tuskr-mcp-server", "--transport", "stdio"]
    }
  }
}

or use uv with source code:

{
  "mcpServers": {
    "tuskr": {
      "transport": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/tuskr-mcp-server",
        "run",
        "src/main.py",
        "--transport",
        "stdio"
      ]
    }
  }
}

Integrate with Claude

Worked examples for Claude Code and the Claude desktop app. Both name the server tuskr, so its tools appear as list_projects, list_test_runs and so on.

Claude Code

Run the server locally over stdio, with credentials passed as environment variables:

claude mcp add --transport stdio tuskr \
  --env TUSKR_TENANT_ID=<your tenant id> \
  --env TUSKR_ACCESS_TOKEN=<your access token> \
  -- uvx tuskr-mcp-server --transport stdio

Everything after -- is the command Claude Code runs to start the server, kept separate from Claude Code's own flags.

Or connect to a shared instance over HTTP:

claude mcp add --transport http tuskr https://<your-mcp-dns-or-ip>/mcp/ \
  --header "Authorization: Bearer <your access token>" \
  --header "Tenant-ID: <your-tuskr-tenant-id>"

Drop the Tenant-ID header if the instance already sets TUSKR_TENANT_ID server-side.

claude mcp add stores the configuration without validating credentials, so a wrong token is only reported when the server is first contacted. Run /mcp inside a session and check that tuskr shows as connected.

Add --scope project to write the entry to the repository's .mcp.json and share it with the team. Keep credentials out of a shared file: reference them as --env TUSKR_ACCESS_TOKEN=${TUSKR_ACCESS_TOKEN} and let each developer supply the value from their own environment.

Claude desktop app

Edit claude_desktop_config.json (Settings, Developer, Edit Config):

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

For a local stdio server:

{
  "mcpServers": {
    "tuskr": {
      "command": "uvx",
      "args": ["tuskr-mcp-server", "--transport", "stdio"],
      "env": {
        "TUSKR_TENANT_ID": "<your tenant id>",
        "TUSKR_ACCESS_TOKEN": "<your access token>"
      }
    }
  }
}

command has to resolve on the app's own PATH, which is not the same as your shell's. If the server fails to start, use the absolute path to uvx.

For a shared HTTP instance:

{
  "mcpServers": {
    "tuskr": {
      "type": "http",
      "url": "https://<your-mcp-dns-or-ip>/mcp/",
      "headers": {
        "Authorization": "Bearer <your access token>",
        "Tenant-ID": "<your-tuskr-tenant-id>"
      }
    }
  }
}

The type key is required on any entry that uses url; without it the entry is read as a stdio server and skipped. Restart the app after editing the file.

Check it works

Ask Claude to list your Tuskr projects. It should call list_projects and come back with project names and IDs. A useful follow-up, since it exercises a filter and a second tool: ask which test runs in a given project are not yet finished, which resolves to list_test_runs with filter_incomplete.

A request such as "mark TC-14 and TC-15 as passed in run TR-3" resolves to a single add_test_run_results call. Bear in mind that several of these tools write to Tuskr, so point the server at a sandbox project while you are still exploring.

Development

Setup

1. Clone repo
2. Install development dependencies: uv sync --dev
3. Create .env from .env.example

Running MCP service

HTTP Transport (Default)

uv run --env-file .env src/main.py

stdio Transport (for local development)

uv run --env-file .env src/main.py --transport stdio

Custom Host/Port

uv run --env-file .env src/main.py --host 127.0.0.1 --port 9000

Running tests

The project uses pytest for testing. The following command will run all tests

uv run pytest -vsx

Running linters

The project uses the ruff tool as a linter.

The following command allows to run linter

uv run ruff check

and this command allow to fix formatting

uv run ruff format

Dockerization

The following command allows to build a docker image

docker build -t tuskr-mcp .

and then you can run it using the

docker run -it tuskr-mcp