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, App Automate runs for Maestro, Espresso and
XCUITest, 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.
Every tool below carries an example prompt. You do not have to phrase it that way, it is there to show the kind of request that resolves to that tool. 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). |
Example prompt: “Log in to TestingBot”
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. |
Example prompt: “Which Chrome versions can I run on Windows 11?”
getDevices
Lists mobile devices (real devices plus emulators/simulators) with their current availability. Takes no parameters.
Example prompt: “Which real iPhones are free right now?”
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). |
Example prompt: “List my last 10 TestingBot tests”
getTestDetails
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
sessionId |
string | Yes | – | The session to fetch full details for. |
Example prompt: “Show me the full details of my most recent failed test, with the video and logs”
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. |
Example prompt: “Mark that session as failed and rename it to Checkout regression”
deleteTest
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
sessionId |
string | Yes | – | The session to delete. |
Example prompt: “Delete the session I just started by mistake”
stopTest
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
sessionId |
string | Yes | – | The running session to stop. |
Example prompt: “Stop the session that is still running”
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). |
Example prompt: “List my last 5 builds”
getTestsForBuild
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
buildId |
string | Yes | – | The build whose tests you want to list. |
Example prompt: “Which tests are in the build called nightly?”
deleteBuild
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
buildId |
string | Yes | – | Deletes the build and all of its tests. |
Example prompt: “Delete the build called scratch-run and everything in it”
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. |
Example prompt: “Upload /Users/me/builds/app-release.apk to TestingBot storage”
uploadRemoteFile
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
remoteUrl |
string | Yes | – | An http/https URL to fetch and store (SSRF-guarded). |
Example prompt: “Upload the build at https://ci.example.com/artifacts/app.ipa to my TestingBot storage”
getStorageFiles
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
offset |
number | No | 0 |
Pagination offset. |
limit |
number | No | 10 |
Number of files to return (max 100). |
Example prompt: “Which app builds do I have in storage?”
deleteStorageFile
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
appUrl |
string | Yes | – | The stored app reference to delete. |
Example prompt: “Delete tb://app123 from storage”
App Automate: Maestro
Run Maestro flows on TestingBot real devices, emulators and simulators. The agent uploads your app, uploads (or writes) the flow YAML, starts a run, and polls until it finishes.
Maestro runs are asynchronous: runMaestroTest returns a run ID
immediately and does not block while devices execute. The agent then polls
getMaestroRunStatus and fetches
getMaestroRunResults once the run completes.
| Tool | Description |
|---|---|
uploadMaestroApp |
Upload the app under test. Returns a project id. |
uploadMaestroFlows |
Upload the flow YAML for a project, from disk or inline. |
runMaestroTest |
Start a run. Returns a run id immediately. |
getMaestroRunStatus |
Poll per-flow progress. |
getMaestroRunResults |
Final outcomes plus the JUnit XML report. |
getMaestroFlowDetails |
Errors, step-level report, video, screenshots and device logs for one flow. |
cancelMaestroRun |
Cancel a running run. |
retryMaestroRun |
Retry a whole run, or a single failed flow. |
uploadMaestroCompanionApp |
Upload a companion app to install alongside the app under test. |
listMaestroProjects |
Find existing projects instead of re-uploading. |
listMaestroRuns |
List runs, or look them up by run name. |
maestroCheatSheet |
Maestro YAML syntax reference for the agent. |
uploadMaestroApp
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
localFilePath |
string | Yes | – | Local path to the .apk, .aab, .ipa or zipped .app. |
Returns a project id that every other Maestro tool takes. Uploads are deduplicated by checksum, so re-running with an unchanged binary reuses the existing project instead of uploading again.
Example prompt: “Upload ./build/app.apk for Maestro testing”
uploadMaestroFlows
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
projectId |
number | Yes | – | Project id from uploadMaestroApp. |
flowsPath |
string | No | – | Directory of .yaml/.yml flows (structure preserved, so runFlow subflows keep resolving), or a pre-built .zip. |
flows |
array | No | – | Inline flows as { fileName, content } objects, for flows the agent writes itself. |
Each upload replaces the flows previously uploaded for that project.
Example prompt: “Upload the flows in ./flows to that project”
runMaestroTest
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
projectId |
number | Yes | – | Project id from uploadMaestroApp. |
platformName |
string | Yes | – |
Android or iOS. |
deviceName |
string | No | any device | Device name, wildcards and regex supported, e.g. Pixel 8, iPhone 1[4-6], *. |
version |
string | No | – | OS version, e.g. 14. |
realDevice |
boolean | No | false |
Run on a physical device instead of an emulator/simulator. Required for .ipa apps. |
name |
string | No | – | Run name shown in the dashboard, and the value listMaestroRuns looks up. |
env |
object | No | – | Environment variables passed to the flows. |
includeTags |
array | No | – | Only run flows carrying these Maestro tags. |
excludeTags |
array | No | – | Skip flows carrying these Maestro tags. |
shardSplit |
number | No | – | Split the flows across this many parallel devices (1–10). |
otherApps |
array | No | – | Up to 4 companion app URLs (tb:// or http(s)://) installed alongside the app under test. |
Example prompt: “Run my Maestro flows on a real Pixel 8 with Android 14”
getMaestroRunStatus
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
projectId |
number | Yes | – | The project to inspect. |
runId |
number | No | – | A specific run. Omit it to list the runs of the latest execution. |
Per-flow statuses are WAITING, READY (running),
DONE, FAILED and CANCELLED,
with failures listed first. The flow ids in this output are what
getMaestroFlowDetails and retryMaestroRun take.
Example prompt: “How is that Maestro run doing?”
getMaestroRunResults
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
projectId |
number | Yes | – | The project. |
runId |
number | Yes | – | The completed run. |
Returns per-flow outcomes, failures first with error messages and video links, plus the JUnit XML report.
Example prompt: “Give me the results of the Maestro run now that it has finished”
getMaestroFlowDetails
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
projectId |
number | Yes | – | The project. |
runId |
number | Yes | – | The run. |
flowId |
number | Yes | – | The flow, taken from getMaestroRunStatus. |
This is the debugging tool: error messages, the step-level JUnit report and links to the video, screenshots and device logs. Fetch it for a failed flow, fix the YAML, upload the flows again, then retry.
Example prompt: “Why did the checkout flow fail? Show me the error and the video”
cancelMaestroRun
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
projectId |
number | Yes | – | The project. |
runId |
number | Yes | – | The run to cancel. |
Example prompt: “Cancel the Maestro run I just started”
retryMaestroRun
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
projectId |
number | Yes | – | The project. |
runId |
number | Yes | – | The run to retry. |
flowId |
number | No | – | Retry only this flow instead of the whole run. |
Example prompt: “Fix the login flow and re-run just that one”
uploadMaestroCompanionApp
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
localFilePath |
string | Yes | – | Local path to the companion .apk, .aab, .ipa or .zip. |
Returns a tb:// app URL to pass in the otherApps
parameter of runMaestroTest (max 4 per run).
Example prompt: “Upload ./build/mock-backend.apk as a companion app for the run”
listMaestroProjects
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
offset |
number | No | 0 |
Pagination offset. |
count |
number | No | 10 |
Number of projects to return (max 100). |
Newest first, with app details, flow names and run ids, so the agent can reuse a project id rather than re-uploading an app.
Example prompt: “What Maestro projects do I already have on my account?”
listMaestroRuns
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
buildName |
string | No | – | Look up runs with this exact run name instead of listing all runs. |
offset |
number | No | 0 |
Pagination offset. Ignored when buildName is set. |
count |
number | No | 10 |
Number of runs to return (max 100). Ignored when buildName is set. |
Returns projectId and runId pairs. The
buildName lookup is what makes prompts like “rerun whatever failed in
last night's nightly build” work.
Example prompt: “Find the Maestro run named nightly and tell me what failed in it”
maestroCheatSheet
Returns a Maestro YAML syntax reference: file structure, commands, selectors and the TestingBot run workflow. Takes no parameters. Agents call this before writing or fixing flows, so the YAML they produce matches what Maestro actually accepts.
Example prompt: “Write me a Maestro flow that logs in and adds an item to the cart”
Maestro tooling requires @testingbot/mcp-server 1.1.0 or later. If your agent
reports that these tools do not exist, update the server, see
Setup & installation.
App Automate: Espresso & XCUITest
Run pre-built Espresso (Android)
and XCUITest (iOS) suites on
TestingBot devices. Every tool takes a framework parameter,
espresso or xcuitest, and follows the same
asynchronous start, poll, fetch pattern as Maestro.
| Tool | Description |
|---|---|
uploadAppAutomateApp |
Upload the app under test. Returns a project id. |
uploadAppAutomateTests |
Upload the test suite for that project. |
runAppAutomateTest |
Start a run. Returns a run id immediately. |
getAppAutomateRunStatus |
Poll run progress. |
getAppAutomateRunResults |
Per-run outcomes plus the JUnit XML report. |
uploadAppAutomateApp
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
framework |
string | Yes | – |
espresso or xcuitest. |
localFilePath |
string | Yes | – | The app under test: .apk/.aab for Espresso, .ipa/.zip for XCUITest. |
Returns the project id used by the other two App Automate tools. For Maestro flows, use uploadMaestroApp instead.
Example prompt: “Upload ./app/build/outputs/apk/debug/app-debug.apk for an Espresso run”
uploadAppAutomateTests
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
framework |
string | Yes | – |
espresso or xcuitest. |
projectId |
number | Yes | – | Project id from uploadAppAutomateApp. |
localFilePath |
string | Yes | – | The instrumented test .apk for Espresso, or the zipped XCUITest runner bundle (.zip). |
Example prompt: “Upload the instrumented test APK for that project”
runAppAutomateTest
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
framework |
string | Yes | – |
espresso or xcuitest. |
projectId |
number | Yes | – | Project id from uploadAppAutomateApp. |
deviceName |
string | No | any device | Device name, wildcards and regex supported, e.g. Galaxy S23, iPhone 1[4-6], *. |
version |
string | No | – | OS version, e.g. 14. |
realDevice |
boolean | No | false |
Run on a physical device instead of an emulator/simulator. |
name |
string | No | – | Run name shown in the dashboard. |
build |
string | No | – | Build identifier used to group runs. |
locale |
string | No | – | Locale for the run, e.g. fr_FR. |
timeZone |
string | No | – | Time zone for the run, e.g. Europe/Brussels. |
testClasses |
array | No | – | Espresso only: run only these fully qualified test classes. |
skipTestClasses |
array | No | – | Espresso only: skip these test classes. |
packages |
array | No | – | Espresso only: run only these packages. |
annotations |
array | No | – | Espresso only: run only tests carrying these annotations. |
testRunner |
string | No | – | Espresso only: custom instrumentation runner. |
Example prompt: “Run the Espresso suite on a real Galaxy S23, only the com.example.LoginTest class”
getAppAutomateRunStatus
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
framework |
string | Yes | – |
espresso or xcuitest. |
projectId |
number | Yes | – | The project to inspect. |
runId |
number | No | – | A specific run. Omit it to list every run in the project. |
Statuses are WAITING, READY (running),
DONE and FAILED. Each run also reports its Appium
session id.
Example prompt: “Is my XCUITest run finished yet?”
getAppAutomateRunResults
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
framework |
string | Yes | – |
espresso or xcuitest. |
projectId |
number | Yes | – | The completed project. |
runId |
number | No | – | XCUITest only: fetch the JUnit report of this single run. |
Example prompt: “Show me the JUnit results for that Espresso project”
Because each Espresso and XCUITest run surfaces its Appium session id, the session tools work on them
too: pass that id to getTestDetails
for the video and screenshots, or to getFailureLogs
for the device and Appium logs.
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.
Example prompt: “Take full-page screenshots of testingbot.com in Chrome on Windows 11 and Safari on macOS”
retrieveScreenshots
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
screenshotId |
string | Yes | – | The job id returned by takeScreenshot. |
Example prompt: “Are those screenshots ready? Give me the image links”
getScreenshotList
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
offset |
number | No | 0 |
Pagination offset. |
limit |
number | No | 10 |
Number of jobs to return (max 100). |
Example prompt: “List my recent screenshot jobs”
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.
Example prompt: “How many testing minutes do I have left?”
updateUserInfo
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
firstName |
string | No | – | New first name. |
lastName |
string | No | – | New last name. |
email |
string | No | – | New email address. |
Example prompt: “Update the last name on my profile to De Vries”
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). |
Example prompt: “Start a live session on Windows 11 in Chrome and open my staging site”
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. |
Example prompt: “Give me a manual Safari session on macOS Ventura pointed at example.com”
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. |
Example prompt: “Open a live session on an iPhone 15 Pro and load my checkout page”
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. |
Example prompt: “Show my team's usage this month and list everyone in it”
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. |
Example prompt: “Start a CDP-enabled Chrome session on Windows 11 and give me the WebSocket URL”
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. |
Example prompt: “List my active tunnels and stop the one I left running this morning”
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). |
Example prompt: “Pull just the failure lines from the Appium and device logs for that session”
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). |
Example prompt: “What test files are in this project?”
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.
Example prompt: “Set this project up to run on TestingBot”
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). |
Example prompt: “Open Chrome on Windows 11”
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. |
Example prompt: “Go to my staging login page”
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.
Example prompt: “What is on the page right now?”
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). |
Example prompt: “Click the Sign in button”
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. |
Example prompt: “Type test@example.com into the email field and press Enter”
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. |
Example prompt: “Read back the dashboard heading”
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. |
Example prompt: “Is the submit button still disabled?”
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. |
Example prompt: “Scroll to the bottom of the page and tell me the document height”
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.
Example prompt: “Take a screenshot of what the browser is showing now”
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. |
Example prompt: “Press Escape to close the modal”
tb_closeBrowser
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
sessionId |
string | Yes | – | Ends the session and frees minutes. |
Example prompt: “Close the session”
tb_listSessions
Lists active automation sessions. Takes no parameters.
Example prompt: “Which automation sessions do I have open?”
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.
Example prompt: “Start a native Android session with the app I just uploaded”
