---
title: Tool reference | TestingBot MCP
description: 'Complete reference for every TestingBot MCP tool: authentication, browsers,
  tests, builds, storage, screenshots, live testing, CDP, tunnels, logs and browser/mobile
  automation.'
source_url:
  html: https://testingbot.com/support/ai/mcp/tools
  md: https://testingbot.com/support/ai/mcp/tools/index.md
---
# Tool reference

This page documents every tool exposed by the TestingBot MCP server. You never call these tools by hand, your AI client (Claude, Cursor, VS Code, Windsurf, and others) calls them on your behalf when you describe what you want in plain language. The names and parameters below are useful when you want to know exactly what an agent can do, or to phrase a prompt precisely.

The tools come from two bundled packages. `@testingbot/mcp-server` handles your account and orchestration (tests, builds, storage, screenshots, live sessions, team, tunnels, logs and project scaffolding). `@testingbot/automation-mcp`, which is bundled automatically, drives live browser and mobile sessions over WebDriver and proxies native app testing to Appium. See [Setup & installation](https://testingbot.com/support/ai/mcp/setup) to connect the server, and [Use cases & workflows](https://testingbot.com/support/ai/mcp/use-cases) for end-to-end examples that chain these tools together.

The first column in each table is the tool name. Parameters are passed by your AI client, not typed by you. If a tool replies with _“No TestingBot credentials configured. Run the tb\_login tool…”_, authenticate first, see [Authentication](https://testingbot.com/support/ai/mcp/authentication).

## Authentication

Logs you in without pasting an API key. After a successful login, credentials are written to `~/.testingbot/credentials` and used automatically, no restart needed. Read more on the [Authentication](https://testingbot.com/support/ai/mcp/authentication) page.

| Tool | Description |
| --- | --- |
| `tb_login` | Browser or device-code login, no key paste required. |

### tb\_login

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `mode` | string | No | `auto` | Login flow: `auto` (loopback on a desktop, device on headless), `loopback` (RFC 8252 local callback), or `device` (RFC 8628 short code at [https://testingbot.com/device](https://testingbot.com/device)). |

## Browser & device

Discover which browsers, platforms and mobile devices are available before you start a session.

### getBrowsers

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `type` | string | No | – | Filter the list: `web` or `mobile`. Omit for all. |

### getDevices

Lists mobile devices (real devices plus emulators/simulators) with their current availability. Takes no parameters.

## Tests

Browse, inspect and manage the test sessions in your account.

### getTests

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `offset` | number | No | `0` | Pagination offset. |
| `limit` | number | No | `10` | Number of tests to return (max 100). |

### getTestDetails

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The session to fetch full details for. |

### updateTest

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The session to update. |
| `name` | string | No | – | New test name. |
| `status` | string | No | – | Mark the test as `passed` or `failed`. |
| `build` | string | No | – | Associate the test with a build. |
| `extra` | string | No | – | Additional metadata as a JSON string. |

### deleteTest

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The session to delete. |

### stopTest

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The running session to stop. |

## Builds

Group related tests into builds and manage them.

### getBuilds

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `offset` | number | No | `0` | Pagination offset. |
| `limit` | number | No | `10` | Number of builds to return (max 100). |

### getTestsForBuild

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `buildId` | string | Yes | – | The build whose tests you want to list. |

### deleteBuild

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `buildId` | string | Yes | – | Deletes the build and all of its tests. |

## Storage

Upload and manage native mobile app binaries (`.apk`, `.ipa`, `.zip`) so they can be installed on devices for native app testing.

### uploadFile

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `localFilePath` | string | Yes | – | Absolute path to a local `.apk`/`.ipa`/`.zip`. |

### uploadRemoteFile

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `remoteUrl` | string | Yes | – | An http/https URL to fetch and store (SSRF-guarded). |

### getStorageFiles

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `offset` | number | No | `0` | Pagination offset. |
| `limit` | number | No | `10` | Number of files to return (max 100). |

### deleteStorageFile

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `appUrl` | string | Yes | – | The stored app reference to delete. |

## Screenshots

Capture a URL across multiple browsers and platforms for cross-browser visual checks.

### takeScreenshot

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `url` | string | Yes | – | The page to capture. |
| `browsers` | array | Yes | – | Array of `{ browserName, version?, os }` targets. |
| `resolution` | string | No | `1920x1080` | Screen resolution to render at. |
| `waitTime` | number | No | `5` | Seconds to wait before capture (0–60). |
| `fullPage` | boolean | No | `false` | Capture the full scrollable page. |

Returns a job id that you pass to `retrieveScreenshots`.

### retrieveScreenshots

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `screenshotId` | string | Yes | – | The job id returned by `takeScreenshot`. |

### getScreenshotList

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `offset` | number | No | `0` | Pagination offset. |
| `limit` | number | No | `10` | Number of jobs to return (max 100). |

## User

Read and update your account profile.

### getUserInfo

Returns account information, name, plan, company, country, available seconds and concurrency. Takes no parameters. Note: `getUserInfo` does not return an email field.

### updateUserInfo

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `firstName` | string | No | – | New first name. |
| `lastName` | string | No | – | New last name. |
| `email` | string | No | – | New email address. |

## Live testing

Start an interactive, manual live session you can watch and control. Each session returns a live-view URL of the form `https://testingbot.com/tests/<sessionId>/live?auth=<hash>`.

### startLiveSession

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `platformType` | string | Yes | – | `desktop` or `mobile`. |
| `desiredURL` | string | Yes | – | The URL to open in the session. |
| `desiredOS` | string | Yes | – | Operating system to run on. |
| `desiredOSVersion` | string | Yes | – | OS version. |
| `desiredBrowser` | string | No | – | Browser to launch (desktop). |
| `desiredBrowserVersion` | string | No | – | Browser version (desktop). |
| `desiredDevice` | string | No | – | Device name (mobile). |

### startDesktopLiveSession

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `desiredURL` | string | Yes | – | The URL to open. |
| `desiredOS` | string | Yes | – | `Windows`, `Mac` or `Linux`. |
| `desiredOSVersion` | string | Yes | – | OS version. |
| `desiredBrowser` | string | Yes | – | `chrome`, `firefox`, `safari`, `edge` or `ie`. |
| `desiredBrowserVersion` | string | No | `latest` | Browser version. |

### startMobileLiveSession

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `desiredURL` | string | Yes | – | The URL to open. |
| `desiredOS` | string | Yes | – | `android` or `ios`. |
| `desiredOSVersion` | string | Yes | – | OS version. |
| `desiredDevice` | string | Yes | – | The device to run on. |

## Team

Inspect your team settings, usage and members.

| Tool | Param | Required | Description |
| --- | --- | --- | --- |
| `getTeam` | – | – | Team settings and usage. No parameters. |
| `getUsersInTeam` | – | – | List all team members. No parameters. |
| `getUserFromTeam` | `userId` | Yes | Fetch a single team member by id. |

## CDP

Spin up a remote browser exposing a Chrome DevTools Protocol endpoint, so you can drive it with Puppeteer or Playwright. See the Playwright/Puppeteer example in [Use cases & workflows](https://testingbot.com/support/ai/mcp/use-cases).

### createCdpSession

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `browserName` | string | Yes | – | Browser to launch. |
| `browserVersion` | string | No | `latest` | Browser version. |
| `platform` | string | Yes | – | Platform to run on. |
| `screenResolution` | string | No | – | Screen resolution. |
| `timeZone` | string | No | – | Time zone for the session. |
| `name` | string | No | – | Session name. |
| `build` | string | No | – | Build to associate the session with. |
| `extraCapabilities` | object | No | – | Additional WebDriver capabilities. |

## Tunnels

Manage TestingBot Tunnels for testing local or firewalled sites.

| Tool | Param | Required | Description |
| --- | --- | --- | --- |
| `getTunnelList` | – | – | List active tunnels. No parameters. |
| `deleteTunnel` | `tunnelId` | Yes | Stop an active tunnel by id. |

## Logs

Fetch and filter the logs for a session, ideal for debugging a failing run.

### getFailureLogs

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The session whose logs you want. |
| `logTypes` | array | No | – | Any of `selenium`, `browser`, `chrome`, `vm`, `appium`. |
| `failuresOnly` | boolean | No | `false` | Return only failure-related entries. |
| `maxBytesPerLog` | number | No | `50000` | Truncate each log (1,000–1,000,000 bytes). |
| `timeoutMs` | number | No | `15000` | Fetch timeout (1,000–60,000 ms). |

## Project

Detect the test framework in a local project and scaffold a ready-to-use TestingBot configuration.

### listTestFiles

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `projectRoot` | string | Yes | – | Root directory of the project to scan. |
| `maxDepth` | number | No | `8` | How deep to recurse (1–15). |
| `maxResults` | number | No | `200` | Maximum files to return (1–2000). |

### setupTestingBot

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `projectRoot` | string | Yes | – | Root directory of the project. |
| `frameworkOverride` | string | No | – | Force a framework instead of auto-detecting. |

Generates a ready-to-paste TestingBot config for the detected framework, Playwright, Cypress, WebdriverIO, Selenium (JS), Nightwatch or Puppeteer.

## Browser automation

These tools come from the bundled `@testingbot/automation-mcp` package and drive a live browser session over WebDriver. They work for desktop browsers and for mobile browsers (on emulators/simulators or real devices). Every session starts with `tb_openBrowser`, which returns a `sessionId` you pass to the other tools, plus a live-view URL (`https://testingbot.com/tests/<sessionId>/live?auth=<hash>`) you can open to watch or take over.

### tb\_openBrowser

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `browserName` | string | Yes | – | `chrome`, `firefox`, `edge` or `safari`. |
| `browserVersion` | string | No | `latest` | Browser version (desktop only). |
| `platform` | string | Yes | – | Desktop codes like `WIN11`/`VENTURA`, or `Android`/`iOS` for mobile. |
| `deviceName` | string | No | – | Mobile only (e.g. `Google Pixel 9`, `iPhone 15 Pro`). Its presence switches the session to mobile. |
| `platformVersion` | string | No | – | Mobile OS version. |
| `automationName` | string | No | `UiAutomator2`/`XCUITest` | Mobile automation engine. |
| `realDevice` | boolean | No | `false` | `true` = physical device, `false` = emulator/simulator. |
| `name` | string | No | – | Session name. |
| `build` | string | No | – | Build to group the session under. |
| `screenResolution` | string | No | – | Screen resolution (desktop only). |

Real-device pre-flight: if `realDevice:true` and the requested device or version is busy or not offered, `tb_openBrowser` returns guidance (wait, use an emulator, or pick an available alternative) **without** starting a session. See [Use cases](https://testingbot.com/support/ai/mcp/use-cases) and [Troubleshooting](https://testingbot.com/support/ai/mcp/troubleshooting).

### tb\_navigate

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The active session. |
| `url` | string | Yes | – | The URL to navigate to. |

### tb\_snapshot

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The active session. |
| `bodyChars` | number | No | `5000` | Body text characters to include (500–50,000). |

Returns a structured summary of the page: title, headings, actionable elements and body text.

### tb\_click

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The active session. |
| `by` | string | No | `css` | Locator strategy: `css`, `xpath`, `id`, `name`, `tag`, `class`, `linkText`, `partialLinkText`. |
| `value` | string | Yes | – | The locator value. |
| `timeoutMs` | number | No | `5000` | Wait timeout (100–30,000 ms). |

### tb\_type

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The active session. |
| `by` | string | No | `css` | Locator strategy. |
| `value` | string | Yes | – | The locator value of the field. |
| `text` | string | Yes | – | Text to type. |
| `clearFirst` | boolean | No | `true` | Clear the field before typing. |
| `pressEnter` | boolean | No | `false` | Press Enter after typing. |

### tb\_getText

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The active session. |
| `by` | string | No | `css` | Locator strategy. |
| `value` | string | Yes | – | The locator value. |
| `timeoutMs` | number | No | `5000` | Wait timeout. |

### tb\_getAttribute

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The active session. |
| `by` | string | No | `css` | Locator strategy. |
| `value` | string | Yes | – | The locator value. |
| `attribute` | string | Yes | – | The attribute name to read. |
| `timeoutMs` | number | No | `5000` | Wait timeout. |

### tb\_executeScript

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The active session. |
| `script` | string | Yes | – | JavaScript to run in the page. |
| `args` | array | No | `[]` | Arguments passed to the script. |

### tb\_screenshot

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The active session. |
| `savePath` | string | No | OS temp dir | A `.png` path or directory to save to. |

Returns an inline image _and_ saves a file, returning a clickable `file://` link. Many clients do not render inline tool images, so open the saved file if you do not see the screenshot in chat.

### tb\_pressKey

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The active session. |
| `key` | string | Yes | – | A W3C key or chord, e.g. `Enter` or `Control+A`. |

### tb\_closeBrowser

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | Ends the session and frees minutes. |

### tb\_listSessions

Lists active automation sessions. Takes no parameters.

## Mobile native apps

For testing native iOS/Android apps (not mobile browsers, use `tb_openBrowser` for those), the automation package proxies to the official appium-mcp. Upload your app first with `uploadFile`, then reference it as `appium:app="tb://<id>"`.

### appium\_session\_management

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `action` | string | Yes | – | One of `create`, `delete`, `list`, `detach`, `select`. |
| `platform` | string | For create | – | `ios` or `android`. |
| `capabilities` | string | No | – | JSON string for `create`: `appium:deviceName`, `appium:platformVersion`, `appium:app="tb://<id>"`. |
| `sessionId` | string | No | – | Required for `delete`, `detach` and `select`. |

Ready to put these together? See [Use cases & workflows](https://testingbot.com/support/ai/mcp/use-cases) for full tool sequences, or return to the [MCP overview](https://testingbot.com/support/ai/mcp).

### Looking for more help?

Have questions or need more information? Reach out via email or Slack.

[Email us](https://testingbot.com/contact/new)[Slack Join our Slack](https://join.slack.com/t/testingb0t/shared_invite/zt-3bcw9xch-jk19~6XPs_xBrsAgAedkCw)