autoit-mcp (portable)

Windows GUI-automation MCP server for Claude Code — drive any desktop app deterministically (launch, wait for windows, click controls/menus/coords, type keys, read text, search pixels) and prove results on disk (a saved/exported file appearing = proof), instead of relying on screenshots.

Backed by the official AutoItX3 DLL (via PyAutoIt, loaded directly — no COM registration). A bundled copy of full AutoIt v3 also enables the .au3 escape hatch (UDFs, _ScreenCapture, registry, complex macros) and Aut2Exe compile. 32 tools, all prefixed au_.

---

What's in this folder

autoit-mcp/
  server.py            the MCP server (single file)
  requirements.txt     mcp + PyAutoIt
  install.ps1          one-shot setup (venv + deps + skill + .mcp.json snippet)
  autoit3/             bundled full AutoIt (AutoIt3_x64.exe, AutoItX, Aut2Exe, Include)
  skill/autoit-gui/    bundled Claude Code SKILL (standalone run+verify+screenshot)
  README.md            this file
  .gitignore
  (.venv/  logs/  mcp.snippet.json   created by install.ps1 at runtime)

~12 MB. Self-contained except for Python (see prerequisites).

The bundled skill (autoit-gui)

This package ships its own Claude Code skill so a fresh machine is fully self-sufficient — it does NOT rely on the run / verify / screen-capture skills (which won't exist there). The skill teaches the model to launch an app, drive menus/controls, take a screenshot via the bundled _ScreenCapture UDF, and prove a save/export by checking the file on disk. install.ps1 copies it to %USERPROFILE%\.claude\skills\autoit-gui\ automatically; restart Claude Code to load it. (To install manually, copy skill\autoit-gui\ there yourself.)

Prerequisites on the new machine

• Windows (uses Win32 + AutoItX).
• Python 3.9+ on PATH (python.org — tick Add Python to PATH). That's the only thing not bundled.
• Claude Code (the host that loads MCP servers).

Install (3 steps)

1. Copy this whole autoit-mcp/ folder anywhere on the new machine (e.g. C:\tools\autoit-mcp).
2. Open PowerShell in the folder and run:

   powershell -ExecutionPolicy Bypass -File .\install.ps1
   

   It creates a local .venv, installs deps, smoke-tests (TOOLS 32), and writes mcp.snippet.json with the correct absolute paths for this machine.
3. Merge that snippet into your project's .mcp.json (under mcpServers), e.g.:

   {
     "mcpServers": {
       "autoit": {
         "command": "C:\\tools\\autoit-mcp\\.venv\\Scripts\\python.exe",
         "args": ["C:\\tools\\autoit-mcp\\server.py"]
       }
     }
   }
   

   Then restart Claude Code and approve the autoit server in /mcp.

No global install, no admin rights, no AutoItX COM registration needed.

Verify it loaded

In Claude Code after restart, the autoit server should expose 32 au_* tools. Quick check from the model: call au_autoit_info → should report run_au3_available: true and point at …\autoit3\AutoIt3_x64.exe (bundled).

---

Tools (32, prefix au_)

Group	Tools
Process	au_run, au_process_close, au_process_exists, au_process_wait_close
Window	au_win_wait, au_win_exists, au_win_activate, au_win_get_pos, au_win_get_text, au_win_get_state, au_win_set_state, au_win_close, au_list_windows
Input	au_send(keys, raw), au_mouse_click(x,y,…), au_mouse_move(x,y)
Menu/Control	au_win_menu_select, au_control_click, au_control_send, au_control_set_text, au_control_get_text, au_statusbar_get_text, au_set_option
Clipboard	au_clip_get, au_clip_put
Pixels (chromeless UIs)	au_pixel_get_color, au_pixel_search
Disk proof	au_file_exists, au_wait_file
Full AutoIt	au_run_au3(script,timeout), au_compile_au3(script_path,out_exe), au_autoit_info()

Defaults: DPI-aware (coords = physical pixels), WinTitleMatchMode=2 (window title matched as a substring anywhere). Every tool returns structured JSON ({ok:true,…} / {ok:false,error}) and never crashes the call. Calls are logged to logs/YYYY-MM-DD.log.

Design choices (vs. a generic "generate .au3" MCP)

• Direct AutoItX DLL calls, not COM Dispatch("AutoItX3.Control") (COM needs regsvr32; the DLL doesn't).
• No temp .au3 for ordinary actions — direct calls are faster + sturdier. .au3 is the escape hatch only (au_run_au3), for what AutoItX lacks.

Gotchas learned on real targets

• au_win_menu_select only works on native Win32/MFC menus. Many modern apps (Qt / WPF / Electron / CEF) use owner-drawn menus that WinMenuSelectItem can't see → it no-ops. For those use accelerators: au_send("{ALTDOWN}{ALTUP}") then "f" then "a" = Save As. Keep au_win_menu_select for classic Win32 apps.
• CEF/Qt welcome/home screens have no native controls and reflow on resize → coordinate clicks are fragile. Prefer launching with a document argument, or use au_pixel_search to find a button.
• The Win11 file dialog ignores classic Edit1/Button1; instead activate it, au_send("^a"), au_send(path, raw=True), au_send("{ENTER}").
• Prove success with au_wait_file(out_path) rather than a screenshot.

Full AutoIt notes

• The bundled autoit3/ makes au_run_au3 + au_compile_au3 work out of the box. The server auto-detects it (no env var needed); you can override with AUTOIT3_EXE or AUTOIT3_DIR.
• ImageSearch is a 3rd-party UDF (not part of standard AutoIt). To enable it, drop ImageSearch.au3 + its DLL into autoit3/Include/, then call it via au_run_au3.
• If you'd rather not bundle AutoIt, delete autoit3/: the 31 DLL-based tools still work; only au_run_au3/au_compile_au3 become unavailable.

Uninstall

Delete the folder. (Nothing is written outside it; no registry, no PATH changes.) Remove the autoit block from your .mcp.json.

Troubleshooting

• Python 3 not found during install → install Python, reopen PowerShell, retry.
• Server doesn't appear in /mcp → ensure the .mcp.json paths match the snippet exactly (absolute, double backslashes) and that you restarted Claude Code.
• au_run_au3 returns "AutoIt3.exe not found" → keep autoit3/ next to server.py, or set AUTOIT3_EXE to a full AutoIt3_x64.exe.
• Coordinates land in the wrong place → the host app may be per-monitor DPI scaled; the server is system-DPI-aware. Use au_win_get_pos to anchor clicks relative to the window, or use au_pixel_search.