PIX4Dmatic MCP

Local MCP server for controlling PIX4Dmatic on Windows through GUI automation.

This first version implements the MVP observation and control layer:

• connect to an already running PIX4Dmatic process

• launch PIX4Dmatic when needed

• focus the PIX4Dmatic window

• capture a screenshot

• send hotkeys or plain text

• click visible UI text or menu-like paths

• inspect the UI Automation tree

• open an existing project file

• start processing from visible processing controls

• wait until PIX4Dmatic becomes idle

• run a guarded JSON job for an existing project or current session

• read recent PIX4Dmatic logs

• check expected output files

• collect diagnostics

Install

Install dependencies:

python -m pip install -r requirements.txt

Optional editable package install:

python -m pip install -e . --no-build-isolation

If package installation is blocked by local permissions, run directly from this checkout:

$env:PYTHONPATH = "src"
python -m pix4dmatic_mcp.server

Run

$env:PYTHONPATH = "src"
python -m pix4dmatic_mcp.server

Configuration

The server loads defaults automatically, then optionally reads:

• PIX4DMATIC_MCP_CONFIG

• pix4dmatic_mcp_config.json in the current working directory

• config/pix4dmatic_mcp_config.json in the current working directory

Useful environment overrides:

• PIX4DMATIC_EXE

• PIX4DMATIC_MCP_DIAGNOSTICS_DIR

See examples/pix4dmatic_mcp_config.example.json.

For Codex or another MCP client, use examples/mcp_config.example.json as a starting point.

Quick Local Checks

PIX4Dmatic is expected to be running in a normal Windows desktop session.

$env:PYTHONPATH = "src"
python scripts/test_status.py
python scripts/inspect_ui.py

MCP Tools

Session and observation:

• pix4d_launch

• pix4d_focus

• pix4d_get_status

• pix4d_screenshot

• pix4d_window_screenshot

• pix4d_get_ui_tree

Low-level UI control:

• pix4d_send_hotkey

• pix4d_type_text

• pix4d_click_text

• pix4d_click_menu

• pix4d_list_menu_items

Project and processing:

• pix4d_open_project

• pix4d_start_processing

• pix4d_wait_until_idle

• pix4d_run_job

• pix4d_run_job_object

• pix4d_run_batch

• pix4d_run_batch_object

Logs and outputs:

• pix4d_read_latest_logs

• pix4d_find_log_errors

• pix4d_check_outputs

• pix4d_analyze_project

• pix4d_detect_blockers

• pix4d_collect_diagnostics

Job Safety

pix4d_run_job_object and pix4d_run_job will start processing. A job must either provide project_path or explicitly set use_current_session to true.

Use dry_run: true to validate job intent without clicking the PIX4Dmatic UI.

Batch files run jobs sequentially. Set continue_on_failure: true to continue after a failed job. See examples/batch.example.json.

Safety

The server only launches PIX4Dmatic and does not expose a generic process runner. It does not automate login or license changes.