Getting Started

The server is designed to be run by an MCP client and you can use this standard config for most of the tools:

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

For tool specific instructions, select your client below for installation instructions.

Cursor

Click the button to install:

Install MCP Server

Or install manually:

Go to Cursor Settings -> MCP -> Add new MCP Server. Name it webdriverio (or to your liking), use command type with the command npx wdio-mcp-server@latest.

VS Code (with compatible agent)

Click the button to install:

Install in VS Code

Or install manually:

  1. Open your settings.json file.
  2. Add or merge the following configuration:
{
  "mcp.servers": {
    "webdriverio": {
      "command": "npx",
      "args": [
        "wdio-mcp-server@latest"
      ]
    }
  }
}
Other Clients (Gemini CLI, etc.)

Most MCP-compatible clients will ask for a command to run the server. Use npx wdio-mcp-server@latest when prompted.

Installation

  • Global (CLI) 
    npm install -g wdio-mcp-server
wdio-mcp-server
  • Local project 
    npm install wdio-mcp-server --save
# then run via npx
npx wdio-mcp-server
  • From source 
    npm install
npm start

Requirements: Node.js >= 18. For mobile support, ensure Appium and platform SDKs are installed and configure APPIUM_* env vars.

Run 

# development
npm run dev

# production
npm start

First Request

  • Start a desktop session 
    POST /session/start
{
"url": "https://httpbin.org/forms/post",
"browserOptions": { "headless": true }
}
  • Execute an action 
    POST /session/{sessionId}/act
{ "action": "click", "elementId": "button_submit" }
  • Terminate the session 
    DELETE /session/{sessionId}

For more, see the API reference and Mobile sections in the sidebar.