webdriverio

This MCP server exposes WebdriverIO as a bridge between a Large Language Model (LLM) and a live browser. It starts a browser session, analyzes the current page to produce a structured, machine-readable context of interactive elements (buttons, inputs, links) with stable element identifiers, and then executes actions requested by the agent (like clicking, typing, or navigating). The LLM can iterate through a loop of reading page context, deciding the next action, and sending that action to the server via the MCP protocol. This enables AI agents to perform complex web interactions with a clear, verifiable model of the page state and available actions.

To use, start the MCP server using your preferred client (the common pattern shown in the repo is to run it via npx). Once running, you can initiate a session by calling the server’s endpoints (e.g., /session/start) to launch a browser, pass a starting URL, and receive a page context. The agent then selects an action (such as click, setValue, navigate) along with the target elementId, and the server returns an updated page context after performing the action. This loop continues until the goal is reached. The server is designed to work with various MCP clients and supports both headless and headed browser modes, configurable through environment variables.

Tools and capabilities include: (1) launching and tidying up browser sessions with configurable timeouts, (2) generating a stable description of page elements with elementId mappings, (3) executing a wide range of WebdriverIO actions (click, setValue, getText, navigate, etc.), and (4) flexible configuration via environment variables for deployment in different environments.

Prerequisites:

• Node.js (v14+ recommended) and npm or pnpm
• Basic familiarity with npm package execution (npx)

Installation steps:

1. Install Node.js from the official site if you don’t have it installed.

2. Install the MCP server package globally or use npx to run it directly from npm registry:

   npm install -g wdio-mcp-server

   or to run without global install (recommended):

   npx wdio-mcp-server@latest

3. Verify installation by starting the server via your usual MCP client workflow. The repository’s example configuration uses:

   { "mcpServers": { "webdriverio": { "command": "npx", "args": ["wdio-mcp-server@latest"] } } }

4. Optional: configure environment variables for your deployment. Common options include enabling headless mode and enforcing a session timeout. For example:

   WEBDRIVERIO_HEADLESS=true WEBDRIVERIO_SESSION_TIMEOUT=300

5. Start a session with a starting URL and begin issuing MCP actions to control the browser.

Tips and notes:

• The server relies on WebdriverIO, so ensure your browser driver (e.g., ChromeDriver) is compatible with the WebdriverIO version you’re using.
• Use stable elementId values in your responses to minimize drift in the agent’s context over time.
• If you run into timeouts, adjust WEBDRIVERIO_SESSION_TIMEOUT and ensure the hosting environment provides adequate resources.
• You can configure multiple MCP servers in the mcp_config, each with its own command and args if you plan to support additional tools.
• For debugging, enable verbose logging in your environment if supported by the MCP server client you’re using.