pywebview-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pywebview-mcp launch the app and take a screenshot"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 appFeatures
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_apimethods 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 ( | AI client's MCP process | No |
Bridge (via | 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-mcpOr install the plugin (MCP + skill):
claude plugin install github:com55/pywebview-mcpRunning 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 guidecwd 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.pyStandard workflow
launch_app(cwd="/path/to/project")screenshot()+get_dom_tree()Interact via
click,type_text, orcall_api("get_ui_state")get_logs()/get_app_output()to debug
Ports
Env var | Default | Purpose |
| 7891 | HTTP bridge (differs from pyside6-mcp's 7890) |
| 9222 | Chrome DevTools for screenshots |
Limitations
Screenshots require
edgechromiumorqtrenderer (CDP). Set automatically by the launcher.Native file dialogs block automation — use
call_apito 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 bridgepywebview_mcp/__main__.py— monkey-patcheswebview.startfor zero-config injection
License
MIT
Available Tools
23 toolscall_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
Scored across 23 tools
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.
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.
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.
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
Related MCP Connectors
Live browser debugging for AI assistants — DOM, console, network via MCP.
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
Web scraping, browser automation, screenshots and AI data extraction for AI agents via MCP.
Web search API and MCP server for developers building AI agents.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceA Playwright-based MCP server that exposes a live browser as a traceable, inspectable, debuggable and controllable execution environment for AI agents.5,213 npm57-
- AlicenseAqualityDmaintenanceAn MCP server for inspecting, debugging, and interacting with PySide6 desktop applications. It enables AI agents to capture UI snapshots, read widget properties, and perform actions like clicking buttons or typing text.223Apache 2.0
- AlicenseAqualityDmaintenanceAn MCP server that gives AI agents the ability to inspect, observe, and automate WKWebViews on connected iOS devices via Safari Web Inspector.141MIT
- AlicenseNot gradedqualityDmaintenanceA lightweight MCP server that enables AI assistants to control Chrome DevTools via CDP for debugging tasks like navigation, screenshots, and JavaScript execution.MIT