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 to connect the server, and Use cases & workflows 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.

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

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.

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 and 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 for full tool sequences, or return to the MCP overview.