agent-browser — Claude Code MCP server: setup
This MCP server gives an AI agent a self-hosted Chrome session with a live noVNC screen that a person can take over.
claude mcp add --env AGENT_BROWSER_URL=<AGENT_BROWSER_URL> --env AGENT_BROWSER_CONTROLLER_TOKEN=<AGENT_BROWSER_CONTROLLER_TOKEN> --env AGENT_BROWSER_OBSERVER_TOKEN=<AGENT_BROWSER_OBSERVER_TOKEN> --transport stdio agent-browser -- npx -y aether-browserWhat agent-browser does
agent-browser exposes one Chrome session to an AI agent through MCP. Its tool set covers opening a session, navigation, page reading, clicking, text entry, key presses, scrolling, status checks, and closing. A person can watch the same browser through noVNC and step in when the agent reaches a login or 2FA prompt.
The local stack is started with Docker Compose and includes Chrome, a virtual display, noVNC, and the API. Claude Code setup uses controller and observer tokens; a remote deployment also takes AGENT_BROWSER_URL. The quickstart requires Docker Engine for Linux with Compose v2, while Docker Desktop and remote-host use are outside that setup path.
What it helps with
- run a dedicated Chrome session for an agent
- watch browser actions through noVNC
- take over at a 2FA checkpoint
- read page state through MCP tools
- end the browser session cleanly
Example prompts for the agent
- Open the page with agent-browser and report its readable content.
- Navigate to the requested URL, then tell me the page title.
- Pause when a 2FA prompt appears and ask me to enter the code in the browser window.
How to install agent-browser
Platform CLI
claude mcp add --env AGENT_BROWSER_URL=<AGENT_BROWSER_URL> --env AGENT_BROWSER_CONTROLLER_TOKEN=<AGENT_BROWSER_CONTROLLER_TOKEN> --env AGENT_BROWSER_OBSERVER_TOKEN=<AGENT_BROWSER_OBSERVER_TOKEN> --transport stdio agent-browser -- npx -y aether-browserReplace <…> with your own values
Platform CLI
codex mcp add agent-browser --env AGENT_BROWSER_URL=<AGENT_BROWSER_URL> --env AGENT_BROWSER_CONTROLLER_TOKEN=<AGENT_BROWSER_CONTROLLER_TOKEN> --env AGENT_BROWSER_OBSERVER_TOKEN=<AGENT_BROWSER_OBSERVER_TOKEN> -- npx -y aether-browserReplace <…> with your own values
Config file
{
"mcpServers": {
"agent-browser": {
"command": "npx",
"args": [
"-y",
"aether-browser"
],
"env": {
"AGENT_BROWSER_URL": "<AGENT_BROWSER_URL>",
"AGENT_BROWSER_CONTROLLER_TOKEN": "<AGENT_BROWSER_CONTROLLER_TOKEN>",
"AGENT_BROWSER_OBSERVER_TOKEN": "<AGENT_BROWSER_OBSERVER_TOKEN>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"agent-browser": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"aether-browser"
],
"env": {
"AGENT_BROWSER_URL": "<AGENT_BROWSER_URL>",
"AGENT_BROWSER_CONTROLLER_TOKEN": "<AGENT_BROWSER_CONTROLLER_TOKEN>",
"AGENT_BROWSER_OBSERVER_TOKEN": "<AGENT_BROWSER_OBSERVER_TOKEN>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e AGENT_BROWSER_URL=<AGENT_BROWSER_URL> -e AGENT_BROWSER_CONTROLLER_TOKEN=<AGENT_BROWSER_CONTROLLER_TOKEN> -e AGENT_BROWSER_OBSERVER_TOKEN=<AGENT_BROWSER_OBSERVER_TOKEN> agent-browser npx -y aether-browserReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about agent-browser
How do I install agent-browser in Claude Code?
Run `claude mcp add agent-browser -e AGENT_BROWSER_CONTROLLER_TOKEN=<AGENT_BROWSER_CONTROLLER_TOKEN> -e AGENT_BROWSER_OBSERVER_TOKEN=<AGENT_BROWSER_OBSERVER_TOKEN> -- npx -y aether-browser`.
What does agent-browser do?
It gives an AI agent MCP tools for operating one Chrome session while a person can watch that session and take control when needed.
Can a person intervene during a 2FA step?
Yes. The server can pause at login, payment, or 2FA prompts so a person can enter the required information in the displayed session.
