webslinger-mcp

webSlinger's MCP server exposes a user's own previously recorded and validated browser automations - "scripts" - as MCP tools, so an agent can call list_scripts and run_script to reliably drive a real website instead of improvising selectors live in the moment. Each script was generated once from a human demonstration of the task and runs deterministically on every call, returning structured JSON output. When no script yet covers a needed task, the agent calls request_demonstration to ask the user to record one.

About

Agents that browse the live web typically re-derive selectors on every single run, which is slow, costly in tokens, and breaks the moment a page's markup drifts - selector drift is one of the most common reliability failures in agentic web browsing. webSlinger takes a different approach: a human demonstrates a task once in their own browser, and webSlinger records that demonstration as a session map and generates a reusable automation script from it. From that point on, the MCP server lets an agent discover and run those already-generated scripts instead of browsing ad hoc. Selectors are made robust by generating them from context-related features of the page - not raw positional selectors - and by generating multiple candidate selectors per element that are cross-validated against the live page and reconciled through a voting mechanism at run time, so a script keeps working even as a page's markup shifts around it. Execution itself is deterministic: no AI drives the browser during a run; the one run-time AI fallback is a self-healing re-detection step used only when a selector fails outright.

Two things about setup are worth stating plainly rather than leaving implicit: this server drives the user's own real, logged-in Chrome profile through a Windows native messaging host (taskSpinner) running on their machine, and it requires an active webSlinger account and API key. It is not a generic, zero-setup public server that anyone can call against an arbitrary site - it is a personal automation layer for the account holder's own previously demonstrated tasks. When no script yet exists for a needed task, the agent can request one: request_demonstration opens a pre-filled briefing page in the user's Chrome so they can record it in a few minutes.

Get the full webSlinger browser extension at webslinger.ai or the Chrome Web Store - it is what records session maps and generates the scripts this server runs.

Related MCP server: Pinchtab MCP Wrapper

Quickstart

This is a structurally accurate, illustrative example of the tool-call sequence - it does not depict any real user's data. The script name checkVendorPortalStatus is a generic stand-in. For real installation and MCP client configuration steps, see Installation and MCP server configuration (mcp_config.json) below.

1. Discover available scripts:

list_scripts()

Illustrative response shape:

{
  "success": true,
  "script_source": "user",
  "scripts": [
    {
      "filename": "checkVendorPortalStatus.js",
      "name": "Check Vendor Portal Status",
      "description": "Logs into the vendor portal and reports the status of open orders.",
      "inputData": [{"name": "vendorId", "type": "string", "example": "12345"}],
      "outputData": [{"name": "orders", "type": "array"}],
      "initialWebsite": "https://vendor-portal.example.com",
      "created_date": "2026-07-10"
    }
  ]
}

2. Run the matching script:

run_script(
    script_name="checkVendorPortalStatus.js",
    input_data={"vendorId": "12345"}
)

This launches the user's Chrome profile, executes the script exactly as if it had been scheduled for that moment, and blocks until the run reaches a terminal state.

Illustrative response shape on success:

{
  "success": true,
  "status": "completed",
  "run_id": "20260710_141530_a3f9",
  "output_data": {
    "orders": [
      {"orderId": "PO-4471", "status": "Shipped", "eta": "2026-07-22"},
      {"orderId": "PO-4472", "status": "Processing", "eta": null}
    ]
  },
  "summary": "{ ... execution report summary: actions run, timing, extraction counts ... }",
  "start_time": "2026-07-10T14:15:31Z",
  "end_time": "2026-07-10T14:16:48Z"
}

run_script always returns a JSON object with a success flag; on an expected failure it returns success: false with a status value the agent can branch on (for example not_configured, not_allowed, script_not_found, busy, throttled, timeout, or failed) rather than throwing.

3. No matching script yet? Ask the user to record one instead of improvising the site interaction:

request_demonstration(
    target_url="https://vendor-portal.example.com/orders",
    task_description="Log in and list the status of all open purchase orders.",
    goals=[
        "array: orders(orderId, status, eta)",
        "input: vendorId - the vendor account to check"
    ]
)

This opens a pre-filled briefing page in the user's own Chrome; the tool returns immediately, and the agent re-checks list_scripts after the user records and the script is generated.

The full tool list is list_scripts, describe_script, run_script, start_run, get_run_status, get_run_report, list_runs, cancel_run, request_demonstration, plus schedule management (create_schedule, list_schedules, delete_schedule). Each tool's docstring in mcp_server.py documents its exact parameters and return shape.

What's in this repository

• mcp_server.py - the MCP server (stdio JSON-RPC), exposing the tools listed above. This is the readable, auditable copy of exactly the file the webSlinger installer places on your machine.

• mcp_config.example.json - a template for your own mcp_config.json (see below).

This repository is not meant to be cloned and run on its own. mcp_server.py imports taskSpinner, the Windows native messaging host that launches Chrome, holds the per-profile run lock, and reads profileRegistry.json. taskSpinner is not published here; it is installed, registered with Chrome, and kept up to date by the webSlinger installer. The copy of mcp_server.py that the installer places next to it - together with a bundled Python runtime and every dependency, including the MCP SDK - is the one you register with your MCP client. Read the source here; run the installed copy.

Installation

1. Install the webSlinger extension from webslinger.ai or the Chrome Web Store.

2. Download webSlinger_Setup.zip from the Install page on webslinger.ai, extract it, and run setup.bat. This installs taskSpinner, the MCP server, the bundled Python runtime, and all dependencies under %LOCALAPPDATA%\webSlinger\, and performs the one-time Chrome native-messaging registration the server relies on. You do not need Python of your own and there is nothing to pip install.

3. Launch one automation from your webSlinger account and click Enable. This grants automation permissions and registers your Chrome profile in profileRegistry.json, which the server reads to know which browser copy to drive.

4. Create ~/webSlinger/taskSpinner/mcp_config.json with your API key (see below), or set the WEBSLINGER_API_KEY environment variable instead.

Note that the MCP server reads its config from and writes its logs and run records under ~/webSlinger/taskSpinner/ (your home directory), not the %LOCALAPPDATA% directory the program files are installed to. Reinstalling or upgrading replaces the program files and leaves your configuration and run history untouched.

Windows only. taskSpinner is a Windows native messaging host; macOS and Linux hosts are planned but not yet available.

MCP server configuration (mcp_config.json)

The MCP server reads ~/webSlinger/taskSpinner/mcp_config.json. Copy mcp_config.example.json and fill in your key. Minimal config:

{
    "api_key": "wsk_..."
}

All fields:

*Alternative: set the WEBSLINGER_API_KEY environment variable, which overrides the file's api_key. Prefer the environment variable when the config file could be committed or shared - the JSON stores the key in plaintext.

The file must be strict JSON: no comments, no trailing commas. A malformed file makes the MCP server exit at startup (Claude Code reports reconnect error -32000); validate with python -m json.tool mcp_config.json.

With no API key configured the server still starts; every tool returns status not_configured with setup instructions.

Identity: which Chrome profile and extension runs

profileRegistry.json (written by the webSlinger extension, next to your local taskSpinner installation) maps apiKeyHash -> {profileName, extensionId}. The extension writes this row itself - at service worker startup and on every schedule operation - so the registered extensionId is by construction the copy that holds that API key (store, unpacked, or build).

Launch resolution precedence:

1. extension_id in mcp_config.json (manual override)

2. the registered extensionId for the configured key's hash

3. legacy by-name scan (only for registry rows written before extensionId registration existed; reload the extension to upgrade the row)

Every launch URL carries the requesting key's hash. The extension compares it against its own stored key and refuses with API_KEY_MISMATCH on disagreement, so a mix-up between accounts fails loudly instead of executing under the wrong one.

Tier limits and usage recording

Execution is gated and recorded per API key on every launch path:

• The MCP server pre-flights an execution-check endpoint and returns status not_allowed (with the server's message) before launching Chrome when your tier has no executions or the monthly limit is exhausted.

• The extension performs the same check itself before every run and fails closed on any error - this is the real enforcement point; the MCP pre-flight is a fast-fail courtesy.

• After each run the extension reports usage, which increments your account's execution counter.

Registering the MCP server

Point your client at the wrapper the installer created, substituting your Windows username. It invokes the bundled Python for you, so the server runs on its own interpreter and its own copy of the MCP SDK and cannot conflict with the package versions in your project's environment.

Claude Code:

claude mcp add webslinger --scope user -- "C:\Users\YourName\AppData\Local\webSlinger\taskSpinner\mcp_server.bat"

Claude Desktop - in %APPDATA%\Claude\claude_desktop_config.json. Backslashes must be doubled; this is JSON, and \U in a Windows path is read as an escape sequence:

{
    "mcpServers": {
        "webslinger": {
            "command": "C:\\Users\\YourName\\AppData\\Local\\webSlinger\\taskSpinner\\mcp_server.bat"
        }
    }
}

Claude Agent SDK - entry in ClaudeAgentOptions.mcp_servers:

"webslinger": {
    "command": r"C:\Users\YourName\AppData\Local\webSlinger\taskSpinner\mcp_server.bat",
    "env": {"WEBSLINGER_API_KEY": "wsk_..."}
}

Write the path out in full rather than using %LOCALAPPDATA% - most MCP clients store the command literally and never expand environment variables.

Machine requirements: Windows, Chrome with the webSlinger extension loaded at least once so profileRegistry.json exists, and automation permissions granted in the extension (launch one automation from webslinger.ai and click Enable). The installer supplies everything else.

Troubleshooting

Logs: ~/webSlinger/taskSpinner/logs/taskSpinner_YYYYMMDD.log. Run records: ~/webSlinger/taskSpinner/outputData/mcpRuns/<run_id>/.

License

MIT - see LICENSE.