se-mcp

<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 50+ 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 — 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:

npx @browsers-cli/se-mcp

Global install (optional)

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):

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

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

Cursor

Add to ~/.cursor/mcp.json:

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

Claude Code

Add to .mcp.json in your project root:

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

Generic MCP client

Use the server.json file included in this package:

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

Tool Catalog

se-mcp exposes 50+ 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:

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

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 — The core Selenium CLI with daemon architecture
• se-cli documentation — Full documentation and guides
• se-cli npm — Core package on npm

License

Apache License 2.0 — see LICENSE for details.