convez.ai
MCP Server
com55

pyside6-mcp

com55/pyside6-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

Playwright-style MCP server for PySide6 apps — lets Claude see, control, and debug your Python desktop GUI

Instalação

$npx convez-ai com55/pyside6-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
10
Forks
2
Acompanhando
1
Saúde
28%
Último commit
há 1 semana
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

pyside6-mcp

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

AI assistant → MCP tools → pyside6-mcp server → HTTP bridge → PySide6 app

Features

  • Screenshot any window or widget
  • Inspect the full widget tree (class, name, geometry, text, state)
  • Click, type, scroll, press keys — full interaction
  • Find widgets by class, objectName, or text content
  • Read Python logs captured from the app
  • Run Python inside the app process for advanced inspection
  • Launch and stop the app directly from Claude

Zero changes to your app's source code required.

Requirements

  • Python 3.11+
  • PySide6 6.6+
  • uv (recommended)
  • Windows (tested), Linux/macOS (should work)

Installation

The MCP server (stdio) and the in-app bridge are separate:

ComponentWhere it runsNeeds PySide6?
MCP server (pyside6-mcp)AI client's MCP processNo
Bridge (python -m pyside6_mcp …)Inside your PySide6 appYes

Target app setup (required)

Install pyside6-mcp into the app's venv so the bridge module is importable:

cd your-pyside6-project
uv add --dev "pyside6-mcp @ git+https://github.com/com55/pyside6-mcp"

MCP server — Claude Code

Option 1 — Plugin (MCP + skill in one command)

claude plugin install github:com55/pyside6-mcp

Installs the MCP server and the companion skill automatically.

Option 2 — MCP server only

Register with Claude Code — pick the scope that fits:

# user: available in every project (recommended for a debug tool)
claude mcp add -s user pyside6 -- uvx --from git+https://github.com/com55/pyside6-mcp pyside6-mcp

# project: only for the current project (saved to .mcp.json, can be committed)
claude mcp add -s project pyside6 -- uvx --from git+https://github.com/com55/pyside6-mcp pyside6-mcp

# local: only for the current project, not committed (default scope)
claude mcp add pyside6 -- uvx --from git+https://github.com/com55/pyside6-mcp pyside6-mcp

Optionally set a custom port with -e:

claude mcp add -s user -e PYSIDE6_MCP_PORT=7890 pyside6 -- uvx --from git+https://github.com/com55/pyside6-mcp pyside6-mcp

MCP server — Cursor

Add the server to your MCP config. Requires uv on PATH.

Global (available in every project — recommended):

OSConfig file
Windows%USERPROFILE%\.cursor\mcp.json
macOS / Linux~/.cursor/mcp.json

Project (committed with the repo): .cursor/mcp.json

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

Optional custom port:

"env": { "PYSIDE6_MCP_PORT": "7890" }

After saving, reload MCP servers in Cursor Settings → MCP (toggle off/on or restart Cursor).

See examples/cursor-mcp-config.json for a copy-paste template.

MCP server — VS Code / GitHub Copilot

VS Code MCP uses the same stdio format. Add to your user or workspace MCP config (Settings → search "MCP" → Edit in settings.json, or .vscode/mcp.json depending on your setup):

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

MCP server — other clients (Windsurf, Cline, OpenCode, …)

Any MCP client that supports stdio servers can use this config block:

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

Place it wherever that client expects MCP config (user-level or project-level). See examples/mcp-config.json for the canonical template.

Note: uvx downloads and runs the MCP server in an isolated env — PySide6 is not required there. PySide6 is only needed in the target app's venv (bridge setup above).

Usage

Launch your app through the bridge (no source changes needed)

# Instead of: python main.py
python -m pyside6_mcp main.py

# With uv
uv run python -m pyside6_mcp main.py

The bridge starts automatically on http://127.0.0.1:7890.

Or: embed the bridge (optional, for always-on)

# In your app's main(), before app.exec()
from pyside6_mcp import install_bridge
install_bridge()

From your AI assistant

Once the app is running with the bridge active, ask your assistant:

"Screenshot the app and click the Apply button" "Why is the checkbox disabled? Inspect its state." "Fill in the form and submit it" "Show me the last 20 log lines from the app"

Your assistant uses the launch_app, screenshot, get_widget_tree, find_widget, click, type_text, get_logs, and other tools automatically.

Tools

ToolDescription
launch_app(command, cwd, port, timeout)Launch app and wait for bridge
stop_app(port)Stop a launched app
screenshot(widget_id?)Capture window or specific widget
get_widget_tree()Full widget hierarchy with IDs
get_widget_info(widget_id)Detailed properties of one widget
get_app_state()Active window, focus, screen info
find_widget(class_name?, object_name?, text?, visible?)Search widgets
click(widget_id?, x?, y?, button?)Mouse click
double_click(widget_id, x?, y?)Double click
type_text(text, widget_id?)Keyboard input
press_key(key)Named key: enter, escape, tab, up/down, f5, …
scroll(dy, widget_id?, dx?)Scroll wheel
get_logs(n?)Recent Python log records
eval_python(code)Execute Python inside the app process

Claude Code Skill

A companion skill is included at skills/pyside6-mcp/SKILL.md. It tells Claude when and how to use these tools automatically — no need to explain the workflow every time.

Install it by copying the skill folder to your Claude skills directory:

# macOS / Linux
cp -r skills/pyside6-mcp ~/.claude/skills/

# Windows (PowerShell)
Copy-Item -Recurse skills\pyside6-mcp "$env:USERPROFILE\.claude\skills\"

Once installed, Claude will automatically read the skill and use the correct workflow whenever you ask it to debug or interact with a PySide6 app.

Architecture

pyside6_mcp/
├── bridge.py      # In-process HTTP server (runs inside the target app)
├── server.py      # FastMCP stdio server (Claude talks to this)
├── __init__.py    # Exports install_bridge()
└── __main__.py    # Launcher: python -m pyside6_mcp <script>

Thread safety: all Qt operations are marshaled to the main thread via QApplication.postEvent with a custom event type — the same mechanism Qt uses internally for cross-thread signals.

Examples

License

MIT

Ver o original no GitHub

Bom para

Relacionados