# 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

## How it works

The basic setup looks like this:

```text
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:

```text
http://localhost:3000/mcp
```

When ngrok is running, the coding agent connects to:

```text
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:

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

Move into the project:

```bash
cd web-agent-mcp
```

If you want to use a different directory name:

```bash
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:

```bash
npm install
```

Install the Chromium browser used by Playwright:

```bash
npx playwright install chromium
```

---

# Build the Project

Build the TypeScript project:

```bash
npm run build
```

The compiled files will be placed in:

```text
dist/
```

---

# Run the MCP Server

For development:

```bash
npm run dev
```

For the compiled version:

```bash
npm start
```

The server runs on:

```text
http://localhost:3000
```

The MCP endpoint is:

```text
http://localhost:3000/mcp
```

The health endpoint is:

```text
http://localhost:3000/health
```

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

Expected response:

```json
{
  "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:

```bash
npm run dev
```

Keep that terminal open.

Open a second terminal and run:

```bash
ngrok http 3000
```

ngrok will give you an HTTPS forwarding URL similar to:

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

Your MCP URL is:

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

Use that `/mcp` URL when configuring your coding agent.

Do not use only:

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

The MCP endpoint is:

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

---

# Keep Both Terminals Running

You need both processes running:

### Terminal 1

```bash
npm run dev
```

### Terminal 2

```bash
ngrok http 3000
```

The flow is:

```text
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:

```text
YOUR_NGROK_URL
```

with the HTTPS URL generated by ngrok.

For example:

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

## Antigravity

Antigravity supports remote MCP servers through `serverUrl`.

Open the MCP configuration in Antigravity and add:

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

For example:

```json
{
  "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:

```text
~/.gemini/config/mcp_config.json
```

A workspace configuration can be placed at:

```text
.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:

```text
.cursor/mcp.json
```

Add:

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

For example:

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

Cursor also supports a global MCP configuration at:

```text
~/.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:

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

For example:

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

Then check the configured MCP servers:

```bash
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:

```text
.vscode/mcp.json
```

Use:

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

For example:

```json
{
  "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:

```text
Command Palette
    -> MCP: List Servers
```

The server should appear as:

```text
web-agent
```

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

---

# GitHub Copilot CLI

GitHub Copilot CLI supports remote HTTP MCP servers.

Run:

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

For example:

```bash
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:

```text
https://YOUR_NGROK_URL/mcp
```

The exact configuration format depends on the client.

The important values are:

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

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

```text
http://localhost:3000/mcp
```

Use the ngrok HTTPS URL instead:

```text
https://YOUR_NGROK_URL/mcp
```

---

# Available MCP Tools

## Navigation

```text
browser_navigate
browser_back
browser_forward
browser_reload
```

## Page inspection

```text
browser_inspect
browser_inspect_semantic
browser_read
browser_get_element
browser_extract
```

## Interaction

```text
browser_click
browser_type
browser_fill_form
browser_select
browser_scroll
browser_keyboard
browser_hover
```

## Screenshots and waiting

```text
browser_screenshot
browser_wait
browser_wait_for_element
browser_wait_for_text
browser_wait_for_navigation
```

## Tabs

```text
browser_new_tab
browser_switch_tab
browser_close_tab
browser_list_tabs
```

## Files

```text
browser_upload_file
browser_download
```

## Browser state

```text
browser_permissions
browser_session
browser_profile
browser_remote
```

## High-level tasks

```text
browser_task
```

---

# Example

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

```text
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:

```bash
npm run dev
```

Build:

```bash
npm run build
```

Run the compiled version:

```bash
npm start
```

Run ngrok:

```bash
ngrok http 3000
```

---

# Project Structure

```text
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:

```bash
PORT=4000 npm run dev
```

On Windows PowerShell:

```powershell
$env:PORT=4000
npm run dev
```

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

```bash
ngrok http 4000
```

---

# Security

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

If you run:

```bash
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:

```bash
npm install
npm run build
```

If the build succeeds, run:

```bash
npm run dev
```

---

## Playwright browser does not start

Install Chromium:

```bash
npx playwright install chromium
```

---

## ngrok connection does not work

Check that the MCP server is running first:

```text
http://localhost:3000/health
```

Then start ngrok:

```bash
ngrok http 3000
```

Make sure the MCP client uses:

```text
https://YOUR_NGROK_URL/mcp
```

and not just:

```text
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](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.