<div align="center">
  <img src="./assets/img/logo.svg" alt="se-mcp" width="280" />
</div>

<p align="center">
  MCP (Model Context Protocol) server for se-cli — exposes all 62 Selenium browser automation tools for AI agents.<br/>
  A thin wrapper that delegates to <a href="https://github.com/se-cli/se-cli">@browsers-cli/se-cli</a>'s MCP server.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@browsers-cli/se-mcp"><img src="https://img.shields.io/npm/v/@browsers-cli/se-mcp?color=22C55E&label=npm" alt="npm version" /></a>
  <a href="https://github.com/se-cli/se-mcp/actions"><img src="https://img.shields.io/github/actions/workflow/status/se-cli/se-mcp/ci.yml?branch=main&label=CI&color=22C55E" alt="CI" /></a>
  <a href="https://github.com/se-cli/se-mcp/blob/main/LICENSE"><img src="https://img.shields.io/github/license/se-cli/se-mcp?color=22C55E" alt="License" /></a>
  <a href="https://github.com/se-cli/se-mcp"><img src="https://img.shields.io/github/stars/se-cli/se-mcp?style=social" alt="Stars" /></a>
  <a href="https://www.npmjs.com/package/@browsers-cli/se-mcp"><img src="https://img.shields.io/npm/dm/@browsers-cli/se-mcp?color=22C55E&label=downloads" alt="npm downloads" /></a>
</p>

---

## Overview

**se-mcp** is the recommended way for MCP-aware AI clients (VS Code, Claude Desktop, Cursor, etc.) to use [se-cli](https://github.com/se-cli/se-cli) — a token-efficient Selenium browser automation CLI.

This package is a thin wrapper around se-cli's built-in MCP server. It provides a standalone entry point (`npx @browsers-cli/se-mcp`) so MCP clients can discover and invoke all browser automation tools without manually configuring the se-cli binary.

### Architecture

```
┌──────────────────┐     JSON-RPC 2.0      ┌──────────────────┐
│  MCP Client      │ ◄─── over stdio ───► │  se-mcp          │
│  (VS Code,       │                       │  (this package)  │
│   Claude, etc.)  │                       │  thin wrapper    │
└──────────────────┘                       └────────┬─────────┘
                                                    │
                                           require() │ delegates to
                                                    ▼
                                           ┌──────────────────┐
                                           │  @browsers-cli/  │
                                           │  se-cli          │
                                           │  MCP Server      │
                                           │  (mcp-server.ts) │
                                           └────────┬─────────┘
                                                    │
                                           JSON line │ over socket
                                                    ▼
                                           ┌──────────────────┐
                                           │  se-cli Daemon    │
                                           │  (long-lived)     │
                                           │  WebDriver +      │
                                           │  Selenium         │
                                           └────────┬─────────┘
                                                    │
                                                    ▼
                                           ┌──────────────────┐
                                           │  Browser         │
                                           │  (Chrome/Edge/   │
                                           │   Firefox)       │
                                           └──────────────────┘
```

The MCP server reads JSON-RPC 2.0 requests from stdin and writes responses to stdout. Browser commands are forwarded to the se-cli daemon over a Unix socket (or Windows named pipe), which holds the WebDriver instance across calls.

## Installation

### For MCP clients (recommended)

You do not need to install anything globally. MCP clients will use `npx` automatically:

```bash
npx @browsers-cli/se-mcp
```

### Global install (optional)

```bash
npm install -g @browsers-cli/se-mcp
```

> **Note:** se-mcp depends on `@browsers-cli/se-cli` as a peer dependency. It will be installed automatically by `npx` or when you install se-mcp with npm 7+.

## Configuration

### VS Code

Add to your VS Code settings (`settings.json`):

```json
{
  "mcp.servers": {
    "se-cli": {
      "command": "npx",
      "args": ["-y", "@browsers-cli/se-mcp"]
    }
  }
}
```

Or use the bundled `server.json` file directly — copy its contents into your MCP client configuration.

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "se-cli": {
      "command": "npx",
      "args": ["-y", "@browsers-cli/se-mcp"]
    }
  }
}
```

### Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "se-cli": {
      "command": "npx",
      "args": ["-y", "@browsers-cli/se-mcp"]
    }
  }
}
```

### Claude Code

Add to `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "se-cli": {
      "command": "npx",
      "args": ["-y", "@browsers-cli/se-mcp"]
    }
  }
}
```

### Generic MCP client

Use the `server.json` file included in this package:

```json
{
  "mcpServers": {
    "se-cli": {
      "command": "npx",
      "args": ["-y", "@browsers-cli/se-mcp"],
      "env": {}
    }
  }
}
```

## Tool Catalog

se-mcp exposes **62 MCP tools** covering the full browser automation lifecycle. All tools are prefixed with `browser_`.

### Session & Browser Management

| Tool | Description |
|------|-------------|
| `browser_open` | Start a browser session (Chrome, Edge, or Firefox) |
| `browser_close` | Close a browser session and stop the daemon |
| `browser_list_sessions` | List all active browser sessions |
| `browser_close_all` | Close all active browser sessions |

### Navigation

| Tool | Description |
|------|-------------|
| `browser_navigate` | Navigate to a URL |
| `browser_go_back` | Navigate back in history |
| `browser_go_forward` | Navigate forward in history |
| `browser_reload` | Reload the current page |
| `browser_get_title` | Get the current page title |
| `browser_get_url` | Get the current page URL |

### Interaction

| Tool | Description |
|------|-------------|
| `browser_click` | Click an element by ref or CSS selector |
| `browser_fill` | Fill an input field with text |
| `browser_type` | Type text into the focused element |
| `browser_press` | Press a keyboard key |
| `browser_select` | Select a dropdown option |
| `browser_check` | Check a checkbox |
| `browser_uncheck` | Uncheck a checkbox |
| `browser_hover` | Hover over an element |
| `browser_dblclick` | Double-click an element |
| `browser_drag` | Drag and drop between elements |

### Snapshot & Search

| Tool | Description |
|------|-------------|
| `browser_snapshot` | Take an accessibility (aria) snapshot with element refs |
| `browser_find` | Find elements by text content |
| `browser_screenshot` | Take a screenshot of the page or element |
| `browser_eval` | Execute JavaScript in the page |

### Tab Management

| Tool | Description |
|------|-------------|
| `browser_tab_list` | List all open tabs |
| `browser_tab_new` | Open a new tab |
| `browser_tab_close` | Close the current tab |
| `browser_tab_select` | Switch to a tab by index |

### Storage & State

| Tool | Description |
|------|-------------|
| `browser_cookie_list` | List all cookies |
| `browser_cookie_get` | Get a specific cookie |
| `browser_cookie_set` | Set a cookie |
| `browser_cookie_delete` | Delete a cookie or all cookies |
| `browser_state_save` | Save browser state to JSON |
| `browser_state_load` | Load browser state from JSON |

### Advanced Input

| Tool | Description |
|------|-------------|
| `browser_dialog_accept` | Accept an alert/confirm/prompt dialog |
| `browser_dialog_dismiss` | Dismiss a dialog |
| `browser_upload` | Upload a file to a file input |
| `browser_resize` | Set the viewport size |
| `browser_keydown` | Press and hold a key |
| `browser_keyup` | Release a held key |
| `browser_mousemove` | Move mouse to coordinates |
| `browser_mousedown` | Press a mouse button |
| `browser_mouseup` | Release a mouse button |
| `browser_mousewheel` | Scroll the mouse wheel |
| `browser_actions_chain` | Chain multiple actions in one call |

### Assertions

| Tool | Description |
|------|-------------|
| `browser_expect` | Assert conditions (visible, hidden, text, value, etc.) |

### Network & Debugging

| Tool | Description |
|------|-------------|
| `browser_highlight` | Outline elements for visual debugging |
| `browser_console` | Get buffered console messages and JS errors |
| `browser_requests` | List buffered network requests |
| `browser_request_detail` | Show details of a specific request |
| `browser_route` | Mock a network route |
| `browser_route_list` | List active route mocks |
| `browser_unroute` | Remove a route mock |

## How It Works

1. **MCP client** (e.g., VS Code) spawns `npx @browsers-cli/se-mcp` as a subprocess.
2. **se-mcp** loads the MCP server from `@browsers-cli/se-cli` and starts listening on stdin/stdout.
3. When the MCP client calls a tool (e.g., `browser_open`), the server maps it to se-cli CLI args and sends them to the **se-cli daemon** over a socket.
4. The **daemon** holds the WebDriver instance and executes the command, returning a JSON response.
5. The server wraps the response in a JSON-RPC 2.0 envelope and writes it to stdout.

### Why a daemon?

The daemon architecture means the browser stays open across tool calls. There is no reconnection cost, no driver restart overhead, and the WebDriver instance is reused. This is what makes se-cli **token-efficient** compared to traditional MCP browser implementations.

### Aria snapshots and element refs

The `browser_snapshot` tool returns a compact YAML-like accessibility tree with element references (`e1`, `e2`, etc.). Subsequent commands can reference these elements by ref instead of verbose CSS selectors, dramatically reducing token usage.

## Programmatic API

You can also use se-mcp programmatically:

```javascript
const { startMcpServer, McpServer, toolDefinitions, mapToolToCliArgs } = require('@browsers-cli/se-mcp');

// Start the MCP server (reads JSON-RPC from stdin, writes to stdout)
startMcpServer();

// Or create an instance with a custom workspace directory
const server = new McpServer('/path/to/workspace');
server.start();
```

### TypeScript

```typescript
import { startMcpServer, McpServer, toolDefinitions, mapToolToCliArgs } from '@browsers-cli/se-mcp';

// startMcpServer(workspaceDir?: string): void
// McpServer: class { constructor(workspaceDir?: string); start(): void }
// toolDefinitions: ToolDef[]
// mapToolToCliArgs(toolName: string, args: any): string[] | null
```

## Related

- **[se-cli](https://github.com/se-cli/se-cli)** — The core Selenium CLI with daemon architecture
- **[se-cli documentation](https://se-cli.github.io/se-site/)** — Full documentation and guides
- **[se-cli npm](https://www.npmjs.com/package/@browsers-cli/se-cli)** — Core package on npm

## License

Apache License 2.0 — see [LICENSE](./LICENSE) for details.