AutoHotkey v2 MCP Server

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

• 25+ AHK_* tools for AutoHotkey workflows
• 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 SSE transport support

Requirements

• Node.js 18+
• npm
• AutoHotkey v2 (for run/validate tools)

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

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"
      }
    }
  }
}

Use absolute paths and escape backslashes in JSON.

Configure AutoHotkey Path and Startup Behavior

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

{
  "action": "set",
  "ahkPath": "C:\\Users\\YourUsername\\Documents\\Design\\Coding\\AutoHotkey\\bin\\AutoHotkey64.exe",
  "waitForStdoutLine": true,
  "stdoutLineTimeoutMs": 300
}

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

Core Tools

• AHK_Smart_Orchestrator: reduce multi-step edit/analysis workflows
• AHK_File_List, AHK_File_View, AHK_File_Edit: file operations
• AHK_Analyze, AHK_Diagnostics: analysis and diagnostics
• AHK_Run: execute scripts (wait, non-wait, window detection)
• AHK_Cloud_Validate: local execution-based validation
• AHK_Doc_Search, AHK_Tools_Search: documentation and tool lookup
• AHK_Config: MCP server configuration

Development Commands

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

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.