Connect a client
Your MCP client launches BrowserControl as a local server over stdio. Plugin installs and the manual uvx browsercontrol examples need uv. If you installed the browsercontrol command yourself, use it directly in your manual configuration.
Codex
codex plugin marketplace add adityasasidhar/browsercontrol
codex plugin add browsercontrol@browsercontrolThe plugin installs the local MCP server and the agent skill together. Make sure uv is on the PATH that Codex uses, then start a new session and ask Codex to use BrowserControl.
The plugin keeps its browser profile and downloads in its Codex plugin data directory.
Claude Code
/plugin marketplace add adityasasidhar/browsercontrol
/plugin install browsercontrol@browsercontrolclaude mcp add --transport stdio browsercontrol -- uvx browsercontrolThe plugin installs the MCP server and the agent skill together; restart Claude Code or run /reload-plugins afterwards. The manual command adds only the server, for the current project. Run /mcp to check the connection.
Clients with an mcpServers file
Most clients read a JSON file with an mcpServers object. Add this entry to it:
{
"mcpServers": {
"browsercontrol": {
"command": "uvx",
"args": ["browsercontrol"]
}
}
}| Client | Where the file lives |
|---|---|
| Claude Desktop | Settings → Developer → Edit Config opens claude_desktop_config.json. |
| Cursor | .cursor/mcp.json in a project, or ~/.cursor/mcp.json for all projects. Docs |
| Gemini CLI | .gemini/settings.json in a project, or ~/.gemini/settings.json. Docs |
| Cline | MCP Servers → Configure → Configure MCP Servers. Docs |
| VS Code (Copilot) | Chat: Open Customizations → MCP Servers → Add Server. In a portable config, add "type": "stdio" to the entry. Docs |
OpenCode
With OpenCode 2.3.2 or later, install the plugin globally:
opencode plugin add github:adityasasidhar/browsercontrol
opencode mcp listThe plugin loads the bundled MCP server and agent skill. If you already configured a server named browsercontrol, the plugin uses that configuration. Open a session and mention @browsercontrol to load the skill.
For manual setup, add the server to your project's opencode.json or your OpenCode user configuration. Select the example for your major version.
{
"mcp": {
"servers": {
"browsercontrol": {
"type": "local",
"command": ["uvx", "browsercontrol"]
}
}
}
}{
"mcp": {
"browsercontrol": {
"type": "local",
"command": ["uvx", "browsercontrol"],
"enabled": true
}
}
}Hermes
hermes mcp add browsercontrol --command uvx --args browsercontrolThis adds the server to your Hermes configuration. Start a new session so Hermes picks it up. It installs the server only, not the agent skill.
OpenClaw
openclaw mcp add browsercontrol --command uvx --arg browsercontrolThis registers the server with OpenClaw and probes it before saving. Restart the gateway or start a new session to load it. It installs the server only, not the agent skill.
Other formats
{
"context_servers": {
"browsercontrol": {
"command": "uvx",
"args": ["browsercontrol"]
}
}
}mcpServers:
- name: browsercontrol
type: stdio
command: uvx
args:
- browsercontrolZed takes the entry in its settings JSON (docs), and Continue in its config.yaml (docs).
From Python
The MCP Python SDK can launch BrowserControl and call its tools from a script:
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
async def main() -> None:
server = StdioServerParameters(command="uvx", args=["browsercontrol"])
async with stdio_client(server) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
result = await session.call_tool("navigate_to", {"url": "https://example.com"})
print(result.content[0].text)
asyncio.run(main())Launch commands
| How you installed | Command | Arguments |
|---|---|---|
| Nothing (uv) | uvx | ["browsercontrol"] |
| Nothing (pipx) | pipx | ["run", "browsercontrol"] |
uv tool, pip, or pipx install | browsercontrol | none |
| Source checkout | uv | ["--directory", "/path/to/browsercontrol", "run", "browsercontrol"] |
A desktop app may not see the same PATH as your terminal. If the client can't find the command, use its full path (which uvx prints it).
Pass settings
Add an env object to the server entry to configure BrowserControl. For example, to run the browser headless:
{
"mcpServers": {
"browsercontrol": {
"command": "uvx",
"args": ["browsercontrol"],
"env": { "BROWSER_HEADLESS": "true" }
}
}
}Every setting is listed in Configuration.
Check the connection
Reload your client's MCP servers or restart it, then look for navigate_to in its tool list. If the server doesn't start, read the client's MCP log and see Troubleshooting.
To share one browser between several clients, run BrowserControl yourself over HTTP instead: see Share over HTTP.
