F
licenseNot graded
qualityD
maintenanceEnables AI agents to interact with QGIS, supporting project management, layer inspection, spatial queries, styling, and map export in both headless and desktop modes.
-
qgis-dev-probe-mcp
by yo-1
Summary: A localhost, development-only MCP bridge for inspecting and operating a running QGIS instance, with observe, act, exec, and wait capabilities gated by mode/opt-in.
Observe (readonly): ping, get_info, list_windows, dump_widgets, screenshot, list_layers, inspect_layer, list_algorithms, get_algorithm_params, list_plugins, read_log, list_recipes.
Act (requires
interactivemode): set_widget, click_widget, trigger_action, close_window, add_layer, remove_layer, run_algorithm, reload_plugin.Execute (requires
interactivemode plus per-session opt-in): execute_code and run_recipe.Utility: wait (MCP-side only) to let deferred GUI actions finish.
Supports inspecting GUI state and screenshots, managing layers, running Processing algorithms, reloading plugins, reading logs, and running plugin-specific recipes.
Enables AI clients to observe and operate a live QGIS instance for plugin development testing, providing tools to inspect windows/widgets, take screenshots, list and inspect layers, list algorithms, trigger actions, add/remove layers, run processing algorithms, reload plugins, and run recipes.
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., "@qgis-dev-probe-mcp trigger the plugin action, screenshot the dialog, and list its widgets"
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.
qgis-dev-probe
QGIS プラグイン開発者向けの開発専用ツール。AI クライアント（Claude Desktop / Claude Code / Codex）から、実機の QGIS を観察・操作して実機検証できるようにします。
QGIS 側: 開発用プラグイン
qgis_dev_probe（localhost のみで待受。既定は停止）AI 側: stdio の MCP サーバー
qgis-dev-probe-mcp
ステータス: 0.1.3 / 実機検証済み。 公式プラグインリポジトリで公開中（2026-11-01 に提出し、2026-11-04 に承認）。Windows 11 + QGIS 3.44.13 で、Claude Desktop・Claude Code・Codex（デスクトップ）の接続、GUI の観察・操作、スクリーンショット、Processing 実行、プラグイン再読込、コード実行の許可ゲートまで実機で確認済みです。他の QGIS バージョン・macOS は未確認です。確認項目は docs/VERIFY.md。
English summary: English.
English
QGIS Dev Probe is a development-only bridge that lets an AI client (Claude Desktop / Claude Code / Codex) inspect and operate a real, running QGIS over MCP, so the AI can verify on the actual machine that the plugin it built really works.
QGIS side: the
qgis_dev_probeplugin (listens on localhost only, stopped by default)AI side: a stdio MCP server,
qgis-dev-probe-mcp
Status: 0.1.3 / verified on a real machine. Published on the QGIS plugin repository (submitted on 2026-11-01, approved on 2026-11-04). Verified on Windows 11 + QGIS 3.44.13 with Claude Desktop, Claude Code, and Codex (desktop): connection, GUI inspection and operation, screenshots, Processing runs, plugin reload, and the permission gates for code execution. Other QGIS versions and macOS are untested. See docs/VERIFY.md.
What it does
Class | Tools | Required permission |
observe | ping, get_info, list_windows, dump_widgets, list_actions, screenshot, list_layers, inspect_layer, list_algorithms, get_algorithm_params, list_plugins, read_log, list_recipes | Always (readonly) |
act | set_widget, click_widget, trigger_action, close_window, add_layer, remove_layer, run_algorithm, reload_plugin |
|
exec | execute_code, run_recipe |
|
local | wait (MCP side only) | - |
A typical check — open a dialog, inspect its widgets, take a screenshot, close it — is described in docs/SCENARIOS.md. Plugin-specific checks are written as recipes (Python files with def run(ctx, args)) kept in the target plugin's own repository and run with run_recipe; this tool does not depend on any specific plugin.
Requirements
QGIS 3.44 (
qgisMinimumVersionis 3.44). Other versions are untested.MCP side: Python 3.10+,
mcp>=2.3,<3(not compatible with the v1FastMCPline).A client that can launch a local stdio MCP server. Browser and smartphone clients cannot use this bridge (they only accept remote HTTPS connectors, and the bridge is localhost-only by design). Which client forms work is summarized at the top of docs/CLIENTS.md.
Setup (short version)
Install the plugin from the QGIS plugin repository (Plugins → Manage and Install Plugins → search "QGIS Dev Probe"), or build the ZIP with
python scripts/package_plugin.pyand install from ZIP.Install the MCP server in a clone of this repository:
python -m venv .venv, thenpip install -e .Register the server in your client (see docs/CLIENTS.md), start QGIS, open "Plugins → QGIS Dev Probe" and press "Start server". Use
interactivemode only when needed.
Full instructions and troubleshooting: docs/SETUP.md (in Japanese). Usage: docs/USAGE.md (in Japanese).
Safety design (summary)
Binds to 127.0.0.1 / ::1 only. A per-start token in
endpoint.json(0600 on POSIX) is verified on every connection.Stopped and
readonlyby default. Theexecute_codeopt-in is never persisted and resets when QGIS restarts.Screenshot output paths are fixed; callers cannot choose them.
This plugin contains two intentional
exec()uses (the session-gatedexecute_codetool and local recipe loading), which are core to its purpose.Development machines only. Do not install on shared or production QGIS setups. Threat model: SECURITY.md.
License
MIT (provisional).
Related MCP server: pyside6-mcp
できること
区分 | ツール | 必要な権限 |
observe | ping, get_info, list_windows, dump_widgets, list_actions, screenshot, list_layers, inspect_layer, list_algorithms, get_algorithm_params, list_plugins, read_log, list_recipes | 常時（readonly） |
act | set_widget, click_widget, trigger_action, close_window, add_layer, remove_layer, run_algorithm, reload_plugin | モード |
exec | execute_code, run_recipe |
|
local | wait（MCP 側のみ） | - |
画面を開いて確認する手順（trigger_action → list_windows → dump_widgets → screenshot → close_window）は docs/SCENARIOS.md。
検証対象プラグイン固有の手順は、そのプラグインのリポジトリに置く recipe（def run(ctx, args) の Python ファイル）を run_recipe で呼びます。このツール自体は特定プラグインに依存しません。
前提
QGIS 3.44 想定。他バージョンは未確認。
metadata.txtの qgisMinimumVersion も 3.44 としています。MCP 側: Python 3.10+、
mcp>=2.3,<3（v1 系FastMCPとは非互換）。対応クライアント: stdio で MCP サーバーを起動できるもの。ChatGPT の Web/アプリは対象外（リモート HTTPS コネクタのみのため）。詳細は docs/CLIENTS.md。
セットアップ（概要）
プラグイン: QGIS のプラグイン管理で「QGIS Dev Probe」を検索してインストールします（公式プラグインリポジトリ）。開発用は
python scripts/package_plugin.pyで ZIP を作り、「ZIP からインストール」でも入れられます。MCP サーバー: このリポジトリを clone し、仮想環境に
pip install -e .で入れます。クライアントに MCP サーバーを登録し（docs/CLIENTS.md）、QGIS のメニュー「プラグイン → QGIS Dev Probe（開発用・AI実機検証）」から「サーバー起動 / Start server」を押します。モードは必要なときだけ
interactiveにします。
詳しい手順とトラブルシューティングは docs/SETUP.md、使い方は docs/USAGE.md。
安全設計（要約）
127.0.0.1 / ::1 以外にはバインドしない。接続ごとにトークン検証（
endpoint.json、POSIX では 0600）。既定は停止 + readonly。
execute_codeの許可は保存されず、QGIS 再起動で失効。スクリーンショットの出力先は固定（呼び出し側はパス指定不可）。
exec()の使用は 2 箇所のみで、いずれもこのプラグインの目的上必要な機能です。execute_code（セッションごとの明示許可制）と、ユーザーがローカルに置いたレシピファイルの読込です。This plugin contains two intentionalexec()uses (the session-gatedexecute_codetool and local recipe loading), which are core to its purpose.開発機専用。 共有・本番の QGIS には入れないでください。脅威モデルは SECURITY.md。
開発
python -m unittest discover -s tests -t . -v
ruff check .構成と設計判断: docs/DESIGN.md / プロトコル: docs/PROTOCOL.md / 貢献: CONTRIBUTING.md
ライセンス
MIT（暫定。変更する場合は LICENSE と pyproject.toml を更新）
Available Tools
24 toolsadd_layerC
Add a vector/raster layer from a local path (GeoPackage sublayer syntax 'file.gpkg|layername=x' works).
Inputs: path (required), kind, name.
click_widgetA
Click a button/checkbox/tool button by objectName or visible text (for QActions / menu items use trigger_action).
The click is deferred; the reply is immediate, so a modal dialog it opens does not block.
Inputs: window (required), text, index, object_name.
close_windowC
Close a window (deferred).
Inputs: window (required).
dump_widgetsA
Dump the widget tree of a window (selector: objectName or title).
Hidden widgets are skipped by default (visible_only); use only_named to cut noise further. Geometry of child widgets is relative to the parent; window geometry is in screen coordinates.
Inputs: window (required), max_items, only_named, visible_only, +1 more.
execute_codeA
Execute arbitrary Python inside QGIS (iface, project in scope; set result). Requires the exec opt-in.
Inputs: code (required).
get_algorithm_paramsC
Parameter and output definitions of a Processing algorithm (e.g. 'native:buffer').
Inputs: algorithm_id (required).
get_infoC
QGIS/Python/Qt versions, platform, profile dir, project, probe home and output dirs.
Inputs: no named parameters.
inspect_layerB
Details of a layer by id or unique name: fields/geometry (vector) or bands/nodata (raster), sample features.
Inputs: layer (required), sample.
list_actionsA
List QActions (menu items, toolbar buttons - where plugins usually put their entry) of a window.
Use text to filter by substring. Pair with trigger_action to launch a plugin.
Inputs: text, window, include_hidden.
list_algorithmsC
Search Processing algorithms by id/name substring.
Inputs: limit, search, provider.
list_layersB
Layers in the current project (id, name, type, crs, public source).
Inputs: no named parameters.
list_pluginsC
Installed plugins with version and active state.
Inputs: no named parameters.
list_recipesB
List recipe files (name + docstring) in the configured recipe directory.
Inputs: no named parameters.
list_windowsB
List top-level windows (objectName, title, class, geometry, modal) and the active modal window.
Inputs: include_hidden.
pingA
Check connectivity; returns plugin version, mode and QGIS pid.
Inputs: no named parameters.
read_logB
Read QGIS message-log entries captured since the probe was loaded. Use since_id to poll for new entries.
Inputs: tag, level, limit, contains, +1 more.
reload_pluginA
Unload, purge modules and reload a plugin so code edits take effect (not for qgis_dev_probe itself).
Inputs: name (required).
remove_layerC
Remove a layer from the project by id or unique name.
Inputs: layer (required).
run_algorithmB
Run a Processing algorithm synchronously. QGIS UI is blocked meanwhile. Returns results and the log.
Inputs: parameters (required), algorithm_id (required), timeout_s.
run_recipeC
Run a recipe (a Python file with def run(ctx, args)) from the configured recipe directory.
Inputs: name (required), args, timeout_s.
screenshotB
Capture QGIS main window, a window, or one widget. Returns the PNG image plus its saved path.
Inputs: name, window, object_name.
set_widgetC
Set a widget value (text, number, bool, combo index/text, ...). Refuses invisible/disabled/read-only widgets.
Inputs: value (required), window (required), object_name (required), index.
trigger_actionA
Trigger a QAction by objectName (preferred) or its visible text (mnemonic '&' ignored).
The trigger is deferred; the reply is immediate, so a modal dialog it opens does not block. Submenus and disabled actions are refused. Check the result with list_windows / screenshot.
Inputs: text, index, window, object_name.
waitA
Sleep (max 60 s) so deferred GUI actions can finish before the next observation.
Inputs: seconds. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
B3.2/5.0
Scored across 24 tools
Disambiguation4/5
Each resource family has clear action boundaries (list vs run vs inspect), and the click_widget/trigger_action distinction is explicitly documented. Minor overlap remains between execute_code and the specialized run_recipe/run_algorithm tools, and ping/get_info both expose diagnostic information, so an agent may occasionally hesitate.
Naming Consistency4/5
All names use lowercase snake_case, and the dominant pattern is verb_noun (list_layers, run_algorithm, get_info). A few utility commands such as ping, wait, and screenshot break the verb_noun pattern but do not create mixed or confusing conventions.
Tool Count3/5
24 tools sit at the upper end of the heavy range, covering many subdomains including GUI control, layers, Processing, plugins, recipes, and diagnostics. Most tools are justified, but the breadth makes the set feel borderline rather than tightly scoped.
Completeness4/5
The surface covers the main dev-probe workflows: GUI inspection/control, layer add/remove/list/inspect, Processing discovery/execution, plugin reload, recipes, logs, and screenshots. Gaps exist in layer/project mutation and feature editing (for example, no update_layer, save_project, or feature CRUD), though execute_code provides a workaround.
Maintenance
ActivityNo data
ResponsivenessOutdated data
Related MCP Connectors
Drive real devices from your AI Coding tool. Embed a client SDK (Unity, Godot, Flutter, iOS/macOS, Android, React Native, Web) in your app, then capture screenshots, traverse the UI tree, inject taps and key events, and run automated test tasks on the physical device over a secure relay.
Build, run, inspect, and continue AgentScript workflows on connected Super Chrome and Mac clients.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Build, test and publish agentic workflows from your AI client: approve steps, read tables, see runs.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables AI assistants to see, control, and debug PySide6 desktop applications without modifying their source code, by capturing screenshots, inspecting widget trees, performing clicks and typing, reading logs, and running Python inside the app process.22192 PyPI9MIT
- AlicenseAqualityCmaintenanceEnables LLMs to control a live Siril GUI session through a bridge, allowing them to run Siril commands and scripts, inspect image state, get previews and statistics, and perform edits such as selections and undo.92GPL 3.0
- AlicenseAqualityCmaintenanceEnables LLM clients to control a live Siril GUI session through an in-app Python bridge, exposing tools to inspect image state and selection, run commands or scripts, get previews and statistics, and undo operations.9GPL 3.0