Browserless MCP in Gemini CLI
Gemini CLI connects to the hosted Browserless MCP server through settings.json, using its httpUrl key for Streamable HTTP. Once it's connected, Gemini CLI can scrape, search, crawl, and drive a cloud browser with the Browserless MCP tools.
- A Browserless API token from your account dashboard, or a Browserless account for OAuth sign-in
- Gemini CLI with a Gemini Code Assist Standard or Enterprise license, or a paid Gemini API key. Google AI Pro, Ultra, and free individual users moved to Antigravity CLI on June 18, 2026; see the migration guide.
Connect to the hosted server
The hosted server runs at https://mcp.browserless.io/mcp, so there's nothing to install.
Add to ~/.gemini/settings.json (or a project-scoped .gemini/settings.json):
{
"mcpServers": {
"browserless": {
"httpUrl": "https://mcp.browserless.io/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
}
}
}
}
Gemini CLI uses httpUrl for Streamable HTTP servers. Its url key means the legacy SSE transport, which the hosted server doesn't support.
To sign in with OAuth instead, drop the headers block. Gemini CLI discovers the OAuth flow when the server first returns 401, and /mcp auth browserless re-authenticates.
To use a region other than US West, add an x-browserless-api-url header, or a browserlessUrl query parameter on the server URL for clients that only take a URL. See regional endpoints.
Run the server locally
To run the MCP server process on your machine instead, use the @browserless.io/mcp npm package over stdio. You need Node.js 24 or newer. Browser work still runs on Browserless, so this is mainly for pinning a server version (add it to the package name, for example @browserless.io/mcp@1.41.0) or pointing at a self-hosted instance with BROWSERLESS_API_URL. Both setups use the server name browserless, so replace the hosted entry with this one rather than adding both.
Add to ~/.gemini/settings.json:
{
"mcpServers": {
"browserless": {
"command": "npx",
"args": ["-y", "@browserless.io/mcp"],
"env": {
"BROWSERLESS_TOKEN": "YOUR_API_TOKEN_HERE"
}
}
}
}
Check the connection
Start Gemini CLI and run /mcp. browserless should be listed as CONNECTED, with its tools underneath.
FAQ & Troubleshooting
Gemini CLI fails to connect even though the URL is right
Check the key is httpUrl, not url. Gemini CLI treats url as an SSE endpoint, and the hosted server doesn't support SSE.
The server connects but every tool call returns 401 Unauthorized
The token is missing or wrong. Copy it again from your account dashboard and check the header reads Bearer followed by the token, with no quotes or trailing whitespace inside the value. If you used an environment variable, confirm it's set in the environment the client was launched from. GUI apps started from the dock or Start menu don't see variables exported in your shell profile.
The connection fails with an SSE error like Non-200 status code (400)
The hosted server speaks Streamable HTTP only and doesn't support the legacy SSE transport. Check the client entry is using its HTTP transport (see the config above), not an SSE one.