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

Related MCP server: Hotkeyless AHK MCP

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 Streamable HTTP transports (stateful or stateless), plus legacy SSE endpoints

• Opt-in bearer-token auth and DNS-rebinding protection for HTTP mode

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

HTTP Mode and Environment Variables

npm start speaks stdio (Claude Desktop). To expose Streamable HTTP on /mcp (plus legacy SSE endpoints), set PORT or pass --sse:

npm run start:sse

Behavior is controlled with environment variables:

Security note: the tool surface includes file writes and process execution. If the HTTP port is reachable by anything other than your own machine, set AHK_MCP_AUTH_TOKEN (e.g. openssl rand -hex 32) and the two allowlists — by default the endpoints accept every request.

See docs/MCP_TRANSPORT_COMPATIBILITY.md for the session flow, stateless mode details, and cURL examples.

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.