ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Use MCP with BrowserStack for Browser Testing

Connect an AI client to BrowserStack MCP for Live, Automate, and private-network testing with local or remote setup instructions.

By the ScreenshotNeo team1 October 20268 min read

Direct answer: connect your AI-enabled client to BrowserStack’s MCP server, then ask the client to launch browser sessions or run supported testing workflows. You can run the MCP server locally with Node.js 22 or later and BrowserStack credentials, or use BrowserStack’s hosted endpoint at https://mcp.browserstack.com/mcp with the documented OAuth flow in supported clients. The browser sessions run on BrowserStack’s cloud infrastructure; MCP is the assistant-facing connection, not a local browser replacement.

What BrowserStack MCP does

Model Context Protocol (MCP) gives an AI client a structured connection to BrowserStack testing tools. You enter a request in an IDE or desktop assistant, the client selects an available MCP tool, BrowserStack executes the action on its hosted infrastructure, and the result or session information returns to the client.

BrowserStack documents MCP workflows for Live, Automate, App Live, App Automate, Accessibility, Percy visual testing, Test Management, AI agents, and Test Reporting & Analytics. Tool availability depends on the BrowserStack product and your account entitlement. The integration does not automatically provide every workflow to every client or account. Read the MCP overview.

Choose local or remote MCP

Option Where the MCP server runs Authentication Best fit
Local server Your development machine BrowserStack username and access key in environment variables Teams that want a local process, project configuration, or direct credential control
Remote server BrowserStack’s hosted endpoint OAuth in the documented VS Code flow Clients that support HTTP MCP servers and teams that prefer hosted setup

This choice changes how the assistant connects to MCP. It does not change which BrowserStack service license a workflow requires.

Prerequisites

  • A BrowserStack account and access to the product workflow you intend to use.
  • An AI-enabled MCP client such as VS Code, Cursor, Claude Desktop, or Cline for the documented local setup.
  • Node.js 22 or later for the local MCP server. Confirm the current requirement in BrowserStack’s getting-started guide.
  • Your BrowserStack username and access key for local setup.
  • A target URL that the selected BrowserStack service can reach. Public sites work directly; localhost, staging, and private networks require BrowserStack Local Testing.

Set up the local BrowserStack MCP server

1. Check Node.js

node --version
# Use Node.js v22 or later

2. Add the MCP server to your client

Use the configuration location and schema required by your client. This general entry uses npx and environment variables so credentials do not need to be committed to a project.

{
  "mcpServers": {
    "browserstack": {
      "command": "npx",
      "args": ["-y", "@browserstack/mcp-server@latest"],
      "env": {
        "BROWSERSTACK_USERNAME": "YOUR_USERNAME",
        "BROWSERSTACK_ACCESS_KEY": "YOUR_ACCESS_KEY"
      }
    }
  }
}

BrowserStack documents both global and project-specific configurations. A global configuration makes the server available across projects for a client; a project configuration scopes it to a directory. Follow the client-specific instructions in Set up the local BrowserStack MCP server.

3. Start and verify the server

  1. Save the configuration in the location expected by your client.
  2. Restart the client or enable the MCP server.
  3. Open the client’s MCP or tools panel.
  4. Confirm that BrowserStack tools are listed before asking the assistant to run a test.

The @latest tag follows the latest published package. If your organization needs repeatable builds, check the current BrowserStack package guidance before choosing a pinned version.

Set up the remote MCP server

BrowserStack documents a hosted MCP endpoint at https://mcp.browserstack.com/mcp. In the documented VS Code flow, add it as an HTTP MCP server and complete OAuth authorization.

{
  "servers": {
    "browserstack": {
      "type": "http",
      "url": "https://mcp.browserstack.com/mcp"
    }
  }
}

Configuration keys and authorization screens vary by client. Use the current instructions in BrowserStack’s remote MCP documentation, then authorize the connection when prompted.

Run a manual browser session with MCP

For cross-browser inspection, ask your assistant to use BrowserStack’s runBrowserLiveSession workflow. Include the URL, browser, operating system, and browser version in the request.

Launch https://example.com in BrowserStack Live using Chrome on Windows 11.
Keep the session interactive and report the session link when it starts.

BrowserStack states that the Live MCP tools require a Live license. If the tool is unavailable or returns an entitlement error, verify that your account includes the required service.

Run automated web tests through MCP

BrowserStack’s MCP tools include Automate workflows for running builds and capturing screenshots. The overview also describes running Playwright and Selenium suites on BrowserStack infrastructure and inspecting failures, logs, and possible fixes.

Run the Playwright suite in ./tests against Chrome and Firefox on the latest supported versions.
Use the project’s existing configuration, return the build summary, and list failed tests with their logs.

Review AI-generated diagnoses and code changes against the underlying test output. The MCP server routes actions and results; an assistant’s interpretation is not proof that a failure has been fixed.

Use MCP with localhost and private staging

BrowserStack Local Testing connects BrowserStack’s cloud browsers to sites hosted on localhost, staging, or private networks behind a proxy, firewall, or VPN. A typical request after Local Testing is active is:

Open https://staging.example.internal in BrowserStack Live using Safari on macOS.
The site is available through the active BrowserStack Local connection.

Do not confuse the two local components:

  • Local MCP server: the process that exposes BrowserStack tools to your AI client.
  • BrowserStack Local Testing: the network connection that lets BrowserStack reach private targets.

Depending on the workflow, you may need both. Read BrowserStack’s Local Testing overview and its JavaScript Local Testing guide for proxy, firewall, VPN, and tunnel details.

Available workflows and license boundaries

Workflow Typical use License note
Live Interactive manual browser sessions BrowserStack explicitly requires a Live license for Live MCP tools.
Automate Playwright or Selenium builds, screenshots, logs, and failure inspection Requires the relevant Automate access.
Accessibility Run accessibility scans Confirm the account entitlement.
Percy Visual testing workflows Confirm Percy access.
Test Management Create projects and cases, start runs, update results BrowserStack explicitly requires a Test Management license.
App Live and App Automate Native mobile app testing Confirm the corresponding app-testing access.
Reporting and analytics Inspect reports and test trends Availability depends on the account and client.

See the current MCP tools and workflows list before designing an automation around a particular tool.

Reliable operating practices

  • Keep credentials in environment variables or the client’s secret store. Never commit an access key or print it in logs.
  • Pin or otherwise review the MCP package version when reproducibility matters.
  • Record the BrowserStack session, build, logs, screenshots, and report links returned by each run.
  • Ask for one browser, operating system, and version at a time when diagnosing a failure; expand the matrix after the first run is understood.
  • Use Local Testing only when the required tunnel and network permissions are active.
  • Treat generated fixes as proposals and rerun the relevant test before merging them.

Performance and cost considerations

MCP adds an assistant-to-tool step, while the browser session and test execution run in BrowserStack’s hosted infrastructure. Keep requests specific so the client invokes the smallest appropriate workflow. A focused Live session or single Automate build is easier to diagnose than a broad request spanning every browser and device.

Costs and entitlements come from the BrowserStack services invoked by the MCP tool. The reviewed documentation explicitly identifies Live and Test Management license requirements; verify current pricing, concurrency, plan limits, and access for other workflows in your BrowserStack account before scaling.

Troubleshooting

The BrowserStack server does not appear in the client

Cause: incorrect configuration path or schema, a disabled server, or an unsupported client setup.

Fix: check the client-specific configuration instructions, confirm the server is enabled, restart the client, and verify Node.js 22 or later for local setup.

Authentication fails on local setup

Cause: incorrect username or access key, misspelled environment variable names, or variables unavailable to the client process.

Fix: confirm BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY, restart the client after changing them, and keep the values out of source control and logs.

The remote server cannot authorize

Cause: the client is using the wrong endpoint or the OAuth flow was not completed.

Fix: use https://mcp.browserstack.com/mcp, follow the client’s HTTP MCP setup, and complete authorization. See the remote server instructions.

A required tool is missing or returns an entitlement error

Cause: the tool belongs to a BrowserStack product that is not enabled for the account. Live and Test Management have explicit license requirements.

Fix: identify the BrowserStack product behind the tool and verify that license before changing the MCP configuration.

Localhost or staging cannot be reached

Cause: BrowserStack Local Testing is inactive, or proxy, firewall, VPN, DNS, or tunnel rules block the connection.

Fix: start the required Local Testing connection, confirm the target resolves from the intended environment, and review network restrictions.

The assistant reports a fix but the test still fails

Cause: the assistant summarized logs or proposed a change without proving the result.

Fix: inspect the underlying session output, screenshots, logs, and test report, then rerun the failing test independently.

Or skip the browser setup

If you only need a clean screenshot or PDF of a URL, ScreenshotNeo provides a single-call API and an MCP server for AI clients such as Claude and Cursor. Cookie banners, newsletter popups, and chat widgets are removed before capture; bot checks, blank pages, timeouts, failed loads, and cache hits are never billed. Each response reports its page verdict and billing status. It also supports full-page and element captures, custom CSS and JavaScript, device presets, dark mode, PDFs, signed links, async jobs, bulk capture, and more.

ScreenshotNeo API documentation:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

An MCP server lets AI agents take screenshots directly. The Free plan includes 1,000 screenshots each month with no card, and paid plans start at $5 for 3,000 screenshots. Create a free ScreenshotNeo account.

FAQ

Does MCP run BrowserStack browsers on my laptop?

No. MCP connects the AI client to BrowserStack’s hosted testing infrastructure. Your client sends tool requests and receives session or test results.

Can I use both local MCP and BrowserStack Local Testing?

Yes. They solve different problems: the local MCP process exposes tools to the assistant, while Local Testing provides network access to private targets.

Is the remote endpoint interchangeable with the local package?

They are two connection methods with different deployment and authentication models. Use the method supported by your client and organization.

Do all BrowserStack MCP tools work with every plan?

No. Tool availability is product-specific, and the documentation explicitly requires Live and Test Management licenses for their respective workflows.

What should be retained for an audit?

Keep the original request, MCP tool call, BrowserStack session or build identifier, logs, screenshots, and final report. Use the assistant’s summary as a convenience, not as the only record.

Keep reading