Web Agent MCP

An MCP server for browser automation built with TypeScript and Playwright.

Web Agent MCP gives AI coding agents access to a real browser through MCP tools. The browser runs on your machine, while the MCP server can be exposed over HTTPS using ngrok so remote coding agents can connect to it.

Features

Web Agent MCP currently provides tools for:

• Web navigation

• Page inspection

• Semantic page inspection

• Clicking and typing

• Form filling

• Selecting options

• Scrolling

• Keyboard actions

• Hovering

• Screenshots

• Waiting

• Browser history

• Multiple tabs

• Structured extraction

• File upload and download

• Waiting for elements, text, and navigation

• Browser permissions

• Browser sessions

• Browser profiles

• Remote browser connections

• Multi-step browser tasks

Related MCP server: Real Browser MCP

How it works

The basic setup looks like this:

AI Coding Agent
      |
      | MCP over HTTPS
      v
    ngrok
      |
      | http://localhost:3000
      v
Web Agent MCP
      |
      v
  Playwright
      |
      v
Chromium Browser

The MCP server listens on port 3000.

The MCP endpoint is:

http://localhost:3000/mcp

When ngrok is running, the coding agent connects to:

https://YOUR-NGROK-DOMAIN/mcp

The browser itself stays on the machine running Web Agent MCP.

Requirements

Before starting, install:

• Node.js 20 or newer

• Git

• GitHub account

• ngrok

• A coding agent that supports MCP

Playwright is included as a project dependency.

Clone the Repository

To create your own copy of the project, clone the repository:

git clone https://github.com/sankalpsinghcoder-ai/web-agent-mcp.git

Move into the project:

cd web-agent-mcp

If you want to use a different directory name:

git clone https://github.com/sankalpsinghcoder-ai/web-agent-mcp.git my-web-agent
cd my-web-agent

If you want your own independent GitHub repository, you can fork the repository on GitHub and then clone your fork.

Install Dependencies

Install the Node.js dependencies:

npm install

Install the Chromium browser used by Playwright:

npx playwright install chromium

Build the Project

Build the TypeScript project:

npm run build

The compiled files will be placed in:

dist/

Run the MCP Server

For development:

npm run dev

For the compiled version:

npm start

The server runs on:

http://localhost:3000

The MCP endpoint is:

http://localhost:3000/mcp

The health endpoint is:

http://localhost:3000/health

You can open the health endpoint in a browser to check that the server is running.

Expected response:

{
  "status": "ok",
  "service": "web-agent-mcp",
  "version": "0.2.0"
}

Expose the MCP Server with ngrok

Because coding agents need to reach the MCP server over the network, expose port 3000 using ngrok.

First, make sure the MCP server is running:

npm run dev

Keep that terminal open.

Open a second terminal and run:

ngrok http 3000

ngrok will give you an HTTPS forwarding URL similar to:

Forwarding https://example-name.ngrok-free.app -> http://localhost:3000

Your MCP URL is:

https://example-name.ngrok-free.app/mcp

Use that /mcp URL when configuring your coding agent.

Do not use only:

https://example-name.ngrok-free.app

The MCP endpoint is:

https://example-name.ngrok-free.app/mcp

Keep Both Terminals Running

You need both processes running:

Terminal 1

npm run dev

Terminal 2

ngrok http 3000

The flow is:

Coding Agent
     |
     v
https://example-name.ngrok-free.app/mcp
     |
     v
ngrok
     |
     v
localhost:3000/mcp
     |
     v
Web Agent MCP
     |
     v
Playwright
     |
     v
Chromium

If you stop ngrok, remote coding agents will no longer be able to connect.

Configure Web Agent MCP

Replace:

YOUR_NGROK_URL

with the HTTPS URL generated by ngrok.

For example:

https://example-name.ngrok-free.app/mcp

Antigravity

Antigravity supports remote MCP servers through serverUrl.

Open the MCP configuration in Antigravity and add:

{
  "mcpServers": {
    "web-agent": {
      "serverUrl": "https://YOUR_NGROK_URL/mcp"
    }
  }
}

For example:

{
  "mcpServers": {
    "web-agent": {
      "serverUrl": "https://example-name.ngrok-free.app/mcp"
    }
  }
}

In Antigravity IDE, MCP servers can be managed from the MCP Servers section. Custom servers can also be added through the raw mcp_config.json configuration.

Antigravity CLI supports global and workspace MCP configuration. The global configuration is:

~/.gemini/config/mcp_config.json

A workspace configuration can be placed at:

.agents/mcp_config.json

After adding the server, reload the MCP configuration and verify that web-agent is connected.

Reference: https://antigravity.google/docs/mcp

Cursor

Cursor supports remote Streamable HTTP MCP servers.

For a project-specific configuration, create:

.cursor/mcp.json

Add:

{
  "mcpServers": {
    "web-agent": {
      "url": "https://YOUR_NGROK_URL/mcp"
    }
  }
}

For example:

{
  "mcpServers": {
    "web-agent": {
      "url": "https://example-name.ngrok-free.app/mcp"
    }
  }
}

Cursor also supports a global MCP configuration at:

~/.cursor/mcp.json

After saving the configuration, restart or reload Cursor if necessary and check that the server appears in the MCP tools.

Cursor CLI uses the same MCP configuration as the IDE.

Reference: https://docs.cursor.com/context/model-context-protocol

Claude Code

Claude Code supports remote HTTP MCP servers.

Run:

claude mcp add --transport http web-agent https://YOUR_NGROK_URL/mcp

For example:

claude mcp add --transport http web-agent https://example-name.ngrok-free.app/mcp

Then check the configured MCP servers:

claude mcp list

The web-agent server should appear in the list.

Claude Code's current remote HTTP configuration uses the MCP URL directly.

Reference: https://code.claude.com/docs/en/mcp

VS Code / GitHub Copilot

VS Code supports HTTP MCP servers through mcp.json.

For a project-level configuration, create:

.vscode/mcp.json

Use:

{
  "servers": {
    "web-agent": {
      "type": "http",
      "url": "https://YOUR_NGROK_URL/mcp"
    }
  }
}

For example:

{
  "servers": {
    "web-agent": {
      "type": "http",
      "url": "https://example-name.ngrok-free.app/mcp"
    }
  }
}

Save the file and start the MCP server from VS Code.

You can verify the connection through:

Command Palette
    -> MCP: List Servers

The server should appear as:

web-agent

Reference: https://code.visualstudio.com/docs/agents/reference/mcp-configuration

GitHub Copilot CLI

GitHub Copilot CLI supports remote HTTP MCP servers.

Run:

copilot mcp add --transport http web-agent https://YOUR_NGROK_URL/mcp

For example:

copilot mcp add --transport http web-agent https://example-name.ngrok-free.app/mcp

The configuration is stored in the Copilot MCP configuration.

You can also inspect the configuration manually.

Reference: https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers

Other MCP Clients

If your coding agent supports Streamable HTTP MCP servers, use:

https://YOUR_NGROK_URL/mcp

The exact configuration format depends on the client.

The important values are:

Transport: Streamable HTTP
URL:       https://YOUR_NGROK_URL/mcp

Do not use the local URL when configuring a remote coding agent:

http://localhost:3000/mcp

Use the ngrok HTTPS URL instead:

https://YOUR_NGROK_URL/mcp

Available MCP Tools

Navigation

browser_navigate
browser_back
browser_forward
browser_reload

Page inspection

browser_inspect
browser_inspect_semantic
browser_read
browser_get_element
browser_extract

Interaction

browser_click
browser_type
browser_fill_form
browser_select
browser_scroll
browser_keyboard
browser_hover

Screenshots and waiting

browser_screenshot
browser_wait
browser_wait_for_element
browser_wait_for_text
browser_wait_for_navigation

Tabs

browser_new_tab
browser_switch_tab
browser_close_tab
browser_list_tabs

Files

browser_upload_file
browser_download

Browser state

browser_permissions
browser_session
browser_profile
browser_remote

High-level tasks

browser_task

Example

Once everything is running, give your coding agent a normal browser task such as:

Visit my GitHub profile at github.com/sankalpsinghcoder-ai, explore the profile and repositories, open a few relevant repositories, inspect their README and available information, and give me a concise summary of what you found.

The agent can decide which browser operations are needed and use the MCP server to perform them.

Development

Start the development server:

npm run dev

Build:

npm run build

Run the compiled version:

npm start

Run ngrok:

ngrok http 3000

Project Structure

web-agent-mcp/
├── src/
│   └── index.ts
├── dist/
├── package.json
├── package-lock.json
├── tsconfig.json
└── .gitignore

dist/ is generated during the build and should not normally be committed to Git.

Configuration

The server uses port 3000 by default.

You can change the port with the PORT environment variable.

For example:

PORT=4000 npm run dev

On Windows PowerShell:

$env:PORT=4000
npm run dev

If you change the port, expose the same port through ngrok:

ngrok http 4000

Security

This project currently exposes a browser-control MCP server through HTTP.

If you run:

ngrok http 3000

the MCP endpoint becomes reachable from the internet through the ngrok URL.

This means anyone who has access to the MCP URL may potentially be able to connect to the server and use the available browser tools, depending on the MCP client's behavior.

Do not expose this setup publicly for sensitive browsing.

In particular, do not use an unauthenticated public tunnel while:

• logged into personal accounts

• accessing banking or financial websites

• accessing private company systems

• handling passwords or authentication tokens

• accessing sensitive files

• using a browser profile containing private sessions

The current project is intended primarily for development and testing.

Authentication and stronger access control should be added before using the server as a public service.

Troubleshooting

MCP server does not start

Run:

npm install
npm run build

If the build succeeds, run:

npm run dev

Playwright browser does not start

Install Chromium:

npx playwright install chromium

ngrok connection does not work

Check that the MCP server is running first:

http://localhost:3000/health

Then start ngrok:

ngrok http 3000

Make sure the MCP client uses:

https://YOUR_NGROK_URL/mcp

and not just:

https://YOUR_NGROK_URL

The coding agent cannot see the tools

Check:

1. The Node server is running.

2. ngrok is running.

3. The ngrok URL is correct.

4. /mcp is included in the URL.

5. The MCP server is enabled in your coding agent.

6. The coding agent has reloaded its MCP configuration.

Roadmap

The project is being developed toward a more capable browser agent with:

• Better semantic DOM understanding

• Stable element identification

• Structured page extraction

• More reliable browser actions

• Better waiting and synchronization

• Authentication and session handling

• Browser profiles

• Remote browser support

• Multi-step browser tasks

• Improved recovery when pages change

• More reliable agent-driven workflows

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contributing

Issues and pull requests are welcome.

If you find a browser action that does not work reliably on a particular website, include:

• The tool being used

• The website or type of page

• What was expected

• What actually happened

• The relevant error message

This makes it easier to reproduce and fix the problem.