Skip to main content
Glama

pywebview-mcp

Playwright-style MCP server for pywebview apps — lets AI assistants see, control, and debug your Python desktop web UI without modifying your app's source code.

AI assistant → MCP tools → pywebview-mcp server → HTTP bridge → pywebview app

Features

  • Screenshot the webview page via CDP (edgechromium/qt)

  • Inspect the full DOM tree (tag, id, role, text, bounds)

  • Click, type, scroll, press keys — full page interaction

  • Find elements by CSS selector, text, role, or tag

  • call_api — invoke js_api methods directly from Python (skip DOM when the app exposes an API)

  • eval_js / eval_python — run code in the page or app process

  • Read Python logs captured from the app

  • Launch and stop the app directly from Claude

Zero changes to your app's source code required.

Related MCP server: qt-mcp

Requirements

  • Python 3.11+

  • pywebview 6.0+

  • uv (recommended)

  • Windows (tested with WebView2), Linux/macOS (should work with supported renderers)

Installation

Component

Where it runs

Needs pywebview?

MCP server (pywebview-mcp)

AI client's MCP process

No

Bridge (via launch_app)

Inside your pywebview app

Uses project's existing pywebview

No changes to the target project. launch_app(cwd=…) injects only the bridge modules via an isolated PYTHONPATH — nothing is added to pyproject.toml, and the MCP server's dependencies (httpx, cffi, …) never enter the app environment.

MCP server — Cursor

Add to %USERPROFILE%\.cursor\mcp.json or project .cursor/mcp.json:

{
  "mcpServers": {
    "pywebview": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/com55/pywebview-mcp", "pywebview-mcp"]
    }
  }
}

Local development:

{
  "mcpServers": {
    "pywebview": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/pywebview-mcp", "pywebview-mcp"]
    }
  }
}

Optional custom port:

"env": { "PYWEBVIEW_MCP_PORT": "7891", "PYWEBVIEW_MCP_CDP_PORT": "9222" }

MCP server — Claude Code

claude mcp add -s user pywebview -- uvx --from git+https://github.com/com55/pywebview-mcp pywebview-mcp

Or install the plugin (MCP + skill):

claude plugin install github:com55/pywebview-mcp

Running your app with the bridge

From MCP (recommended — zero project setup):

launch_app(cwd="/path/to/project")                              # main.py at root
launch_app(cwd="/path/to/project", script="app.py")             # other name at root
launch_app(cwd="/path/to/project", script="backend/gui.py")   # entry in subfolder
get_launch_help()                                               # full script decision guide

cwd is the project root (pyproject.toml). script is the entry .py relative to cwd.

Manual equivalent (same isolated PYTHONPATH that launch_app builds):

cd your-pywebview-project
# PYTHONPATH must point at a directory that contains *only* pywebview_mcp
# (bridge modules). Do not point it at the MCP server's site-packages.
uv run python -m pywebview_mcp main.py

Standard workflow

  1. launch_app(cwd="/path/to/project")

  2. screenshot() + get_dom_tree()

  3. Interact via click, type_text, or call_api("get_ui_state")

  4. get_logs() / get_app_output() to debug

Ports

Env var

Default

Purpose

PYWEBVIEW_MCP_PORT

7891

HTTP bridge (differs from pyside6-mcp's 7890)

PYWEBVIEW_MCP_CDP_PORT

9222

Chrome DevTools for screenshots

Limitations

  • Screenshots require edgechromium or qt renderer (CDP). Set automatically by the launcher.

  • Native file dialogs block automation — use call_api to set paths instead.

  • Element IDs reset on every app restart — call get_dom_tree() again.

  • uvx cache — after updating the package, clear uv cache or use a local path.

Architecture

  • pywebview_mcp/server.py — FastMCP stdio server (no pywebview dependency)

  • pywebview_mcp/bridge.py — in-process HTTP bridge

  • pywebview_mcp/__main__.py — monkey-patches webview.start for zero-config injection

License

MIT

Available Tools

23 tools
call_apiB

Call a js_api method directly on the Python object exposed to the page. Example: call_api("get_state") when the app exposes state via js_api.

Inputs: method (required), args, kwargs. Returns: result

clickA

Click an element or page coordinate.

  • element_id only: clicks the center of that element

  • element_id + x/y: clicks at offset within element bounds

  • x/y only: clicks at viewport coordinates

Inputs: x, y, button, element_id. Returns: result

double_clickC

Double-click an element.

Inputs: element_id (required), x, y. Returns: result

eval_jsC

Execute JavaScript in the webview page and return the result.

Inputs: code (required). Returns: result

eval_pythonA

Evaluate Python in the app process. Context: window, webview, api (js_api object). WARNING: debugging only.

Inputs: code (required). Returns: result

find_elementB

Search DOM elements by CSS selector, tag, html id, ARIA role, text, or visibility. Examples: find_element(selector="#launch-btn") find_element(text="Launch") find_element(role="button")

Inputs: tag, role, text, html_id, +2 more. Returns: result

get_app_outputA

Get the last n lines of the launched app's stdout/stderr. Only works for apps started via launch_app on this server.

Inputs: n, port. Returns: result

get_app_stateA

Get app-level state: page title, URL, focus element, pywebview platform.

Inputs: no named parameters. Returns: result

get_app_statusB

Report process + bridge health; detect likely native dialog blocks.

Inputs: port. Returns: result

get_dom_treeA

Get the DOM tree of the page as JSON. Each element has: id, tag, html_id, class, role, text, visible, bounds, children. Use element IDs from this tree in other tools.

Inputs: no named parameters. Returns: result

get_element_infoA

Get detailed properties of a specific DOM element by MCP id.

Inputs: element_id (required). Returns: result

get_launch_helpA

Return how to call launch_app — especially the script parameter.

Call this before launch_app when you are unsure which entry .py to use or whether script should include a subfolder path.

Inputs: no named parameters. Returns: result

get_logsB

Get the last n Python logging records from the app.

Inputs: n. Returns: result

launch_appA

Launch a pywebview app with the MCP bridge injected, then wait until the UI is ready.

Inputs: cwd (required), port, script, command, +2 more. Returns: result

list_actionsA

List clickable buttons, links, and role=button elements.

Inputs: no named parameters. Returns: result

press_keyA

Press a key on the focused element. Named keys: enter, escape, tab, backspace, delete, arrows, space, home, end, f1–f6.

Inputs: key (required). Returns: result

screenshotA

Capture a screenshot of the webview page (or a specific element by ID). Uses CDP (edgechromium/qt renderer). Call this first to orient yourself.

Inputs: element_id.

scrollB

Scroll the page or an element. dy > 0 scrolls down.

Inputs: dy (required), dx, element_id. Returns: result

stop_appB

Stop a previously launched app (started via launch_app).

Inputs: port. Returns: result

trigger_actionA

Click a button/link by html id (name) or visible text without DOM traversal.

Inputs: name, text. Returns: result

type_textB

Type text into an input element (focuses it first).

Inputs: text (required), element_id. Returns: result

wait_for_idleA

Wait until the page has been quiet (no DOM mutations) for quiet_ms.

Inputs: timeout, quiet_ms. Returns: result

wait_until_readyC

Wait until DOM is ready and pywebview API is available.

Inputs: timeout, quiet_ms. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 23 tools

    Disambiguation3/5

    Most tools have distinct purposes, but there is notable overlap between get_app_status, get_app_state, get_app_output, and get_logs — all retrieve different kinds of app information. Also, trigger_action, click, and double_click all perform clicking actions, though their contexts differ.

    Naming Consistency4/5

    Tool names generally follow a verb_noun pattern (get_app_status, find_element, type_text), but a few deviate: wait_until_ready/wait_for_idle use different prepositional forms, screenshot is a noun-as-verb, and eval_python/eval_js break the get_* pattern. Overall still recognizable.

    Tool Count4/5

    23 tools is on the heavier side but appropriate for a pywebview automation server that needs to cover app lifecycle, DOM inspection, interaction, and evaluation. Each tool addresses a distinct aspect of webview control, so the count is justified.

    Completeness4/5

    The toolset covers the full lifecycle: launch, wait, interact (click, type, press, scroll), inspect (DOM, elements, state), evaluate (JS, Python, API), log retrieval, and stop. Minor gaps like explicit navigation or window resizing exist, but these may be unnecessary for pywebview's fixed-window model.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers