AutoHotkey v2 MCP Server

A TypeScript MCP server for AutoHotkey v2 development. It provides script analysis, file operations, documentation search, and script execution tools for MCP clients such as Claude Desktop.

Architecture

Highlights

• 12 core tools by default, more in opt-in toolsets (see Tools and toolsets)
• AHK_Check: one checker that uses AutoHotkey’s own /Validate when available
• AHK_Navigate: definition, references, rename and symbols through THQBY’s v2 language server
• Six read-only uia_* tools that feed live UI Automation ground truth to the model, so it writes correct selectors instead of guessing them
• Focused file discovery and active-file aware operations
• Script execution with process tracking and window detection
• Local AutoHotkey validation and diagnostics tools
• Built-in AutoHotkey docs and prompt/context helpers
• Stdio and Streamable HTTP transport support, with opt-in legacy SSE compatibility

UIA inspection

Writing UIA automation without inspecting the live tree means guessing selectors. These tools remove the guesswork:

uia_windows  ->  uia_tree  ->  uia_find / uia_element  ->  paste snippet  ->  uia_highlight
   which          what's         the exact control        into your .ahk      confirm it is
   window         in it          + verified selector      script              the right one

They are in the uia toolset; enable it with AHK_MCP_TOOLSETS=core,uia or AHK_Settings { "action": "enable_toolset", "toolset": "uia" }.

Every element result carries a paste-ready AHK v2 snippet that has been executed against the live tree and confirmed to resolve back to that exact element. Paths are property chains, not RuntimeIds, so they still work after the target app restarts.

All six tools are strictly read-only — they read properties and pattern availability but never invoke a control pattern, so none of them can press, toggle, select, or delete anything in the target app.

Full reference, including the selector-validation hook and Electron/WebView2 guidance: docs/UIA_INSPECTION.md.

Requirements

• Node.js 20+
• npm
• AutoHotkey v2 (for AHK_Run, AHK_Eval and AHK_Check’s interpreter engine)
• Optional: THQBY’s AutoHotkey v2 Language Support VS Code extension, for AHK_Navigate and AHK_Check’s language-server engine. It is found automatically in the VS Code extensions folder, or set AHK_THQBY_LSP_SERVER to its server/dist/server.js

Installation

git clone https://github.com/truecrimedev/ahk-mcp.git
cd ahk-mcp
npm install
npm run build

Run

npm start

Development mode:

npm run dev

Smoke test:

npm run smoke:mcp
npm run smoke:http
npm run test:evals    # eval grader tests
npm run eval:tasks    # task evals with and without the server (see evals/README.md; costs API credits)

Claude Desktop Configuration

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "ahk": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\Users\\YourUsername\\path\\to\\ahk-mcp\\dist\\index.js"],
      "env": {
        "NODE_ENV": "production",
        "AHK_MCP_LOG_LEVEL": "warn",
        "AHK_MCP_TOOLSETS": "core",
        "AHK_MCP_SCRIPT_DIR": "C:\\Users\\YourUsername\\Documents\\AutoHotkey"
      }
    }
  }
}

Use absolute paths and escape backslashes in JSON. A ready-to-edit template is in .mcp.example.json.

Claude Code on Windows

From the repo root in PowerShell:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\setup-claude-code.ps1

It builds the server, registers it with Claude Code as ahk, and sets up permissions, MCP timeouts and an AutoHotkey /Validate hook for edited .ahk files. Add -WhatIf to preview. Options and troubleshooting: docs/CLAUDE_CODE_WINDOWS.md.

File Access

File tools only read and write inside allowed directories: the client’s MCP roots, AHK_MCP_SCRIPT_DIR, the scriptDir/searchDirs set with AHK_Config, the server’s working directory, and AHK_MCP_ALLOWED_DIRS. Paths are checked after resolving symlinks, and writes through a symlink are refused.

Configure AutoHotkey Path and Startup Behavior

Use AHK_Config to set the executable path and non-blocking startup behavior:

{
  "action": "set",
  "ahkPath": "C:\\Program Files\\AutoHotkey\\v2\\AutoHotkey64.exe",
  "waitForStdoutLine": true,
  "stdoutLineTimeoutMs": 300
}

This is used by AHK_Run (and AHK_Cloud_Validate path resolution).

Tools and toolsets

Every tool a server lists costs context in every session, so only the core toolset is listed by default. Pick toolsets with AHK_MCP_TOOLSETS (comma-separated, or all), or at runtime with AHK_Settings (enable_toolset, disable_toolset, reset_toolsets); the server then sends tools/list_changed. AHK_Settings is always listed.

• AHK_Check replaces the analysis tools. It runs up to three engines: AutoHotkey itself with /Validate (loads the script without running it: the authoritative load-time errors), THQBY’s language server, and built-in static checks. Static errors become warnings when an authoritative engine ran. Results come back as text and as structuredContent.
• AHK_Navigate does symbols, definition, references, hover, workspace_symbols and rename through one long-lived THQBY process. Without THQBY, symbols, definition and references fall back to a text search marked approximate. Rename previews by default.
• AHK_Eval { "reset": true } replaces AHK_Repl_Reset.

Development Commands

npm run build
npm run clean
npm run lint
npm run test
npm run test:integration
npm run smoke:mcp
npm run smoke:http

Documentation

• docs/README.md
• docs/QUICK_START.md
• docs/QUICKREFERENCE.md
• docs/MCP_TRANSPORT_COMPATIBILITY.md
• docs/ARCHITECTURE_DIAGRAMS.md
• docs/RELEASE_NOTES.md

Contributing

See CONTRIBUTING.md and AGENTS.md.

License

MIT. See LICENSE.