Setup & installation

This guide walks you through installing the TestingBot MCP server and connecting it to your AI client. The server runs locally and is started on demand by your client through npx, so there is nothing to install globally and nothing to keep running yourself.

New to TestingBot MCP? Start with the overview to understand what the server can do. For everything about logging in, see the dedicated Authentication page.

Prerequisites

Before you begin, make sure you have the following:

Node.js 18 or higher (20+ recommended). The server is launched with npx, which ships with Node.js. Check your version with node -v.
An MCP-compatible client such as Claude Desktop, Claude Code, Cursor, VS Code (Copilot/MCP), Windsurf, or any other client that supports the Model Context Protocol over stdio.
A TestingBot account. You can sign up for free if you do not have one yet.

You do not need to paste an API key to get started. The recommended way to sign in is the tb_login tool, which opens a browser and captures your credentials without copy/paste. Authentication is covered in full on the Authentication page.

Install

The TestingBot MCP server is distributed as the @testingbot/mcp-server NPM package. It bundles @testingbot/automation-mcp, which adds live browser and mobile automation tools, so a single install gives you both account management and automation capabilities.

You do not install the package by hand. Instead you add a small configuration entry to your MCP client that tells it to launch the server with npx. The command your client will run is:

npx -y @testingbot/mcp-server@latest

The -y flag lets npx download the package the first time without prompting, and @latest ensures you always start the most recent version.

1-click installers

For VS Code and Cursor you can skip the manual configuration with a 1-click installer, which writes the MCP config for you:

For Claude Desktop you can install the .mcpb bundle from the MCP server releases page, Claude will configure the server automatically.

The standard configuration below is identical for every client, only the location of the config file changes. Pick your client in the tabs in the next section.

Per-client configuration

Select your client below. Each tab shows where the configuration file lives and the JSON to add. Two variants are shown for each client:

Browser login (recommended): no key in your config. After the server starts, ask your agent to run tb_login and authorize in the browser.
API key: set TESTINGBOT_KEY and TESTINGBOT_SECRET in the env block. Best for CI and shared configurations. Get your keys at your account settings.

Edit Claude Desktop's claude_desktop_config.json. You can open it from Settings → Developer → Edit Config, or find it at:

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

Browser login (recommended), no key, run tb_login afterwards:

{
  "mcpServers": {
    "testingbot": {
      "command": "npx",
      "args": ["-y", "@testingbot/mcp-server@latest"]
    }
  }
}

API key variant:

{
  "mcpServers": {
    "testingbot": {
      "command": "npx",
      "args": ["-y", "@testingbot/mcp-server@latest"],
      "env": {
        "TESTINGBOT_KEY": "<key>",
        "TESTINGBOT_SECRET": "<secret>"
      }
    }
  }
}

Save the file and restart Claude Desktop. The TestingBot tools will appear in the tools menu.

Claude Code reads MCP servers from a .mcp.json file in your project root (or your user config). The quickest way is the CLI:

claude mcp add testingbot -- npx -y @testingbot/mcp-server@latest

To configure it by hand instead, create or edit .mcp.json in your project root.

Browser login (recommended), no key, run tb_login afterwards:

{
  "mcpServers": {
    "testingbot": {
      "command": "npx",
      "args": ["-y", "@testingbot/mcp-server@latest"]
    }
  }
}

API key variant:

{
  "mcpServers": {
    "testingbot": {
      "command": "npx",
      "args": ["-y", "@testingbot/mcp-server@latest"],
      "env": {
        "TESTINGBOT_KEY": "<key>",
        "TESTINGBOT_SECRET": "<secret>"
      }
    }
  }
}

Run /mcp inside Claude Code to confirm the testingbot server is connected.

Use the 1-click installer for Cursor, or configure it manually by creating or opening .cursor/mcp.json in your project (or ~/.cursor/mcp.json for a global config).

Browser login (recommended), no key, run tb_login afterwards:

{
  "mcpServers": {
    "testingbot": {
      "command": "npx",
      "args": ["-y", "@testingbot/mcp-server@latest"]
    }
  }
}

API key variant:

{
  "mcpServers": {
    "testingbot": {
      "command": "npx",
      "args": ["-y", "@testingbot/mcp-server@latest"],
      "env": {
        "TESTINGBOT_KEY": "<key>",
        "TESTINGBOT_SECRET": "<secret>"
      }
    }
  }
}

Restart Cursor. The TestingBot server will appear under Settings → MCP.

Use the 1-click installer for VS Code, or configure it manually. Open the command palette (Ctrl+Shift+P / Cmd+Shift+P), run MCP: Add Server, and choose the NPM package method with @testingbot/mcp-server.

You can also edit the workspace file .vscode/mcp.json directly. Note that VS Code nests servers under a servers key:

Browser login (recommended), no key, run tb_login afterwards:

{
  "servers": {
    "testingbot": {
      "command": "npx",
      "args": ["-y", "@testingbot/mcp-server@latest"]
    }
  }
}

API key variant:

{
  "servers": {
    "testingbot": {
      "command": "npx",
      "args": ["-y", "@testingbot/mcp-server@latest"],
      "env": {
        "TESTINGBOT_KEY": "<key>",
        "TESTINGBOT_SECRET": "<secret>"
      }
    }
  }
}

Reload the window. The TestingBot tools become available to Copilot Chat in agent mode.

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. You can also open it from Settings → Cascade → MCP Servers → Manage MCPs.

Browser login (recommended), no key, run tb_login afterwards:

{
  "mcpServers": {
    "testingbot": {
      "command": "npx",
      "args": ["-y", "@testingbot/mcp-server@latest"]
    }
  }
}

API key variant:

{
  "mcpServers": {
    "testingbot": {
      "command": "npx",
      "args": ["-y", "@testingbot/mcp-server@latest"],
      "env": {
        "TESTINGBOT_KEY": "<key>",
        "TESTINGBOT_SECRET": "<secret>"
      }
    }
  }
}

Refresh the MCP servers list in Windsurf to connect.

Any MCP-compatible client can launch the server over stdio. Add an entry that runs the standard command. Most clients use the mcpServers shape below:

Browser login (recommended), no key, run tb_login afterwards:

{
  "mcpServers": {
    "testingbot": {
      "command": "npx",
      "args": ["-y", "@testingbot/mcp-server@latest"]
    }
  }
}

API key variant:

{
  "mcpServers": {
    "testingbot": {
      "command": "npx",
      "args": ["-y", "@testingbot/mcp-server@latest"],
      "env": {
        "TESTINGBOT_KEY": "<key>",
        "TESTINGBOT_SECRET": "<secret>"
      }
    }
  }
}

If your client uses a different key (for example servers instead of mcpServers), keep the command, args and optional env values exactly as shown and adapt the wrapper to your client's format.

We recommend the browser-login variant: it keeps long-lived API secrets out of config files. After the server starts, ask your agent to run tb_login. See Authentication for the full flow, including the device-code option for SSH and headless environments.

If you use the API-key variant, treat your config file like a secret. Avoid committing files that contain TESTINGBOT_SECRET to source control.

Verify your setup

Once your client has loaded the server, confirm everything works by asking your AI agent to perform a simple read-only action:

"List my recent TestingBot tests"

"Show my TestingBot account info"

Behind the scenes these run the getTests and getUserInfo tools. A successful response lists your tests, or returns account details such as your name, plan, company, country, available seconds and concurrency.

What success looks like

The TestingBot tools appear in your client's tool list (often shown as a tools or MCP icon).
The agent returns real account data rather than an error.
No restart is needed after authenticating, credentials are picked up automatically.

If you see “Run tb_login”

If a tool replies with a message like “No TestingBot credentials configured. Run the tb_login tool…”, the server started successfully but is not yet authenticated (this is the expected state for the browser-login variant). Ask your agent to run tb_login and complete the sign-in:

"Run tb_login to authenticate with TestingBot"

On a desktop this opens your browser so you can click Authorize. On a remote or headless host, it prints a short code, open https://testingbot.com/device, enter the code, and authorize. Full details are on the Authentication page.

Run into a problem? The Troubleshooting page covers common issues such as Node version errors, the server not appearing, and credential prompts.

Next steps

Now that the server is installed and verified, continue with:

Authentication, browser login, device-code flow, API keys and where credentials are stored.
Tool reference, every tool the server exposes, grouped by category.
Use cases & workflows, end-to-end examples and the prompts that drive them.
FAQ, quick answers to common questions.