Browserless MCP in Qwen Code
Qwen Code connects to the hosted Browserless MCP server over Streamable HTTP, added with the qwen mcp CLI or the httpUrl key in settings.json. Once it's connected, Qwen Code 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
- Qwen Code installed
Connect to the hosted server
The hosted server runs at https://mcp.browserless.io/mcp, so there's nothing to install.
Set BROWSERLESS_TOKEN in your environment, then run in your terminal:
qwen mcp add --transport http browserless https://mcp.browserless.io/mcp \
--header 'Authorization: Bearer $BROWSERLESS_TOKEN'
The single quotes keep the shell from expanding the variable, so the settings file stores $BROWSERLESS_TOKEN and Qwen Code resolves it when it loads settings. This writes the entry to ~/.qwen/settings.json. Add --scope project to write .qwen/settings.json in the current project instead. The token stays out of that file, and Qwen Code holds the server as pending until you run qwen mcp approve browserless. To edit the file by hand, add:
{
"mcpServers": {
"browserless": {
"httpUrl": "https://mcp.browserless.io/mcp",
"headers": {
"Authorization": "Bearer $BROWSERLESS_TOKEN"
}
}
}
}
If you signed in to browserless with OAuth before, remove the server first, in the scope you added it to: qwen mcp remove --scope user browserless, or qwen mcp remove --scope project browserless from the project directory. Qwen Code sends stored OAuth tokens in place of the Authorization header, and removing the server also deletes its stored tokens. qwen mcp remove defaults to user scope and deletes the tokens only when it finds the server in that scope, so a project entry needs --scope project.
Qwen Code 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, leave out --header (or the headers block). Qwen Code discovers the OAuth flow when the server first returns 401 and opens a browser window. You can re-run sign-in from the server's Auth actions in the /mcp dialog.
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 ~/.qwen/settings.json:
{
"mcpServers": {
"browserless": {
"command": "npx",
"args": ["-y", "@browserless.io/mcp"],
"env": {
"BROWSERLESS_TOKEN": "$BROWSERLESS_TOKEN"
}
}
}
}
Qwen Code expands $VAR_NAME and ${VAR_NAME} in env values, so set BROWSERLESS_TOKEN in your environment before starting it, or paste the token in place of the variable.
Check the connection
If you use OAuth, start qwen first and complete the sign-in from the /mcp dialog. qwen mcp list doesn't start OAuth, so before that a fresh OAuth entry shows as disconnected.
Run qwen mcp list. browserless should show as connected. Inside a session, /mcp opens the MCP dialog, where you can see the server's tools and manage OAuth sign-in.
FAQ & Troubleshooting
Qwen Code fails to connect even though the URL is right
Check the key is httpUrl, not url. Qwen Code treats url as an SSE endpoint, and the hosted server doesn't support SSE. If you used qwen mcp add, check it wrote httpUrl, and pass --transport http to set the transport explicitly.
The server added with --scope project doesn't load
Qwen Code gates servers in a project's .qwen/settings.json until you approve them. Run qwen mcp approve browserless in that project, then restart Qwen Code.
The local server shows Disconnected (timed out after 10000ms)
The first npx run downloads @browserless.io/mcp, which can take longer than qwen mcp list waits. Run npx -y @browserless.io/mcp once in a terminal, stop it with Ctrl+C after it starts, then run qwen mcp list again.
The OAuth sign-in never completes on a remote machine
Qwen Code's OAuth callback listens on http://localhost:7777/oauth/callback, so the browser has to run on the same machine as Qwen Code. Qwen Code accepts a public --oauth-redirect-uri for remote setups, but the hosted Browserless server only accepts loopback callbacks from CLI clients. On a remote server or cloud IDE, use the API token header instead.
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.