Give Your AI Coding Assistant Real Eyes, Hands, and a Debugger for AutoHotkey v2
An MCP server that turns Claude, Antigravity, and other AI assistants from “guessers” into precise AutoHotkey v2 systems architects.
If you’ve ever asked an AI to write an AutoHotkey v2 script, you’ve probably watched it confidently produce code that mixes v1 and v2 syntax, hardcodes the wrong window class, or quietly invents a function that doesn’t exist. The model is flying blind — it can’t see your active window, it doesn’t know which libraries you already have on disk, and it certainly can’t run or debug what it just wrote.
The AutoHotkey v2 MCP Server fixes all of that. Built in Python on top of the open Model Context Protocol standard, it plugs directly into AI assistants like Claude Code and Antigravity and exposes a focused toolbox: validate syntax, run scripts with captured stdout, inspect the active window, search your global library, and — the headline feature — attach a live DBGp debugger to any running AHK script.
Why AHK v2 Needs This
AutoHotkey v2 brought strict object-oriented syntax to a language that used to forgive almost anything. The upside is real classes, real errors, and real types. The downside is that a single misplaced brace or stray v1 command crashes the script on load — and the AI has no idea until the user pastes the popup back into chat.
Worse, AHK is fundamentally a desktop language. Half the value of any script depends on the window it’s targeting, the library wrappers you’ve already built, and whether the process is currently running. None of that is in the AI’s training data — it lives on your machine, right now. This server is the bridge.
What’s in the Box
| Capability | What the AI Can Now Do |
|---|---|
| validate_ahk_syntax | Run code through AHK’s /Validate switch and catch syntax errors before handing the script to you. |
| run_ahk_script | Execute a temporary script with captured stdout and a hard timeout, so the AI can actually test logic — “does this regex really match?” — instead of guessing. |
| inspect_active_window | Pull the title, ahk_class, and ahk_exe of whatever window you have focused. Just say “write a script for my active window” and watch it grab the exact selectors. |
| search_global_library | Symbol-aware search of your master AHK library — classes, functions, and methods by name with file:line precision. No more reinvented WebSocket wrappers. |
| Process tools | list_ahk_processes, find_ahk_script, and kill_ahk_script let the AI discover and clean up running scripts without asking you for a PID. |
| Action history + GUI | Every script the AI runs is logged to %AppData% with workspace affinity. A bundled AHK v2 GUI lets you browse, preview, and one-click restore any past script. |
| Full DBGp debugger | Attach, break, step, inspect variables, set breakpoints, evaluate expressions, and even dbg_set_var at runtime — the same protocol SciTE4AutoHotkey uses. |
The Killer Feature: A Live Debugger for the AI
This is what changes the game. Other AHK assistants stop at “here’s some code, good luck.” This server lets the model take the next step — diagnose the problem itself.
The flow looks like this:
- “My UIA-tester script seems stuck.”
- The AI calls
find_ahk_script("UIA-tester")and gets the PID. - It calls
dbg_attach(pid), thendbg_break()to pause execution. dbg_stack()shows it’s hung insideMyFunction()at line 42.dbg_get_vars()revealsretryCount = 999— an infinite retry loop.dbg_eval("retryCount := 0")patches the live variable.dbg_continue("run")lets the script proceed, thendbg_detach()cleans up.
All of that happens inside one chat turn. And because every dbg_* tool accepts a session_id, the server supports truly concurrent debug sessions — break one script while another keeps running, no blocking.
How to Set It Up
No JSON files. No config editing. No environment variable wrangling. Setup is literally three steps:
- Download the server folder and drop it anywhere on your machine.
- Open a chat with your AI assistant (Claude Code, Antigravity, or any MCP-aware client).
- Tell it the absolute path to the folder and say something like:
“Connect to the MCP server in this directory.”
That’s it. The AI handles the wiring, picks up the tools, it will ask for restart and you’re ready to go. Once it’s connected, try this prompt to see the difference:
“Can you use the AutoHotkey v2 MCP? How does it feel to have these tools at your disposal?”
You’ll see your assistant transform from a guessing chatbot into a precise systems architect that can see your desktop, read your library, and debug your scripts.
Try Asking
Once it’s hooked up, things you couldn’t ask before suddenly work:
- “Inspect my active window and tell me its class.”
- “Attach to my script (PID 1234) and find out why it’s stuck.”
- “Write a new automation using my existing local libraries — search them first.”
- “Highlight row X on my active Excel workbook using ComObject.”
- “I have an AutoHotkey error popup; diagnose and fix it.”
- “Show me the last 5 things you did,” or “Restore the script from my last execution to this folder.”
Free to Use, Free to Adapt
The AutoHotkey v2 MCP Server is licensed under Creative Commons Attribution 4.0 (CC BY 4.0). You’re free to use it, modify it, and build on it — commercially or otherwise — as long as you give appropriate credit. The whole point of MCP is portable, model-neutral tools; this server works with any MCP-aware client, today and tomorrow.
If you write AHK v2 with an AI in the loop, this is the missing piece. Plug it in once and the difference is immediate: your assistant stops guessing about windows it can’t see, stops rewriting libraries you already own, and starts debugging the scripts it ships instead of leaving you to do it.
Ready to try it? Download the server, point your AI at the folder, and ask it to inspect your active window. You’ll feel the upgrade in the first reply.
