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.