AutoHotkey v2

You can leverage the AutoHotkey v2 MCP Server to provide intelligent code analysis, file management, and context-aware assistance for AutoHotkey v2. This server augments development by orchestrating tools, delivering contextual help, and enabling streamlined workflows with specification-driven tooling.

How to use

You interact with the MCP server through a client that communicates via standard MCP protocols. Use the server to analyze AutoHotkey v2 code, run scripts with window detection, and obtain context-rich guidance and documentation alongside your code. You can request tasks like automated file analysis, code completion suggestions, diagnostics, and contextual help that reference built-in AutoHotkey v2 documentation.

How to install

Prerequisites before installing the AutoHotkey v2 MCP Server:

• Node.js 18.0.0+

• npm

• yarn

How to install

Step by step setup to get the MCP server running locally:

# 1) Clone the repository
git clone https://github.com/TrueCrimeAudit/ahk-mcp.git
cd ahk-mcp

# 2) Install dependencies
npm install

# 3) Build the project
npm run build

# 4) Start the server (production)
npm start

# Optional: for development with auto-reload
npm run dev

Claude Desktop configuration

Configure Claude Desktop to use the MCP server. You will provide a JSON snippet mapping server name to the command that starts the server and environment settings.

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

Claude Desktop configuration debug

For troubleshooting, you can enable a debug log level and use a separate server configuration entry.

{
  "mcpServers": {
    "ahk-server": {
      "autoApprove": [
        "analyze_code",
        "find_variables",
        "get_function_info",
        "get_class_info"
      ],
      "disabled": false,
      "timeout": 60,
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\path\\to\\ahk-mcp\\dist\\index.js"],
      "transportType": "stdio",
      "env": {
        "NODE_ENV": "production",
        "AHK_MCP_LOG_LEVEL": "debug"
      }
    }
  }
}

MCP Jam configuration

If you manage MCP servers through MCP Jam, you can add this server as a stdio-type entry using the following example.

{
  "mcpServers": {
    "ahk-mcp": {
      "type": "stdio",
      "name": "ahk-mcp",
      "command": "node",
      "args": ["C:\\Users\\YourUsername\\path\\to\\ahk-mcp\\dist\\server.js"],
      "env": {
        "NODE_ENV": "production",
        "AHK_MCP_LOG_LEVEL": "warn"
      }
    }
  }
}

Additional setup notes

If you prefer to run the server directly via npm, use the start command after building: npm run build followed by npm start. For development with auto-reload, you can use npm run dev.

MCP Tools

The server exposes a suite of tools for AutoHotkey v2 development. These tools include orchestration, script execution, diagnostics, analysis, and a set of built-in prompts. You can expect improved consistency, performance, and context-driven assistance across your workflow.

Built-in AutoHotkey prompts

The server includes ready-to-use prompts for common AutoHotkey v2 tasks, accessible through your client’s prompt or commands interface.

Documentation

The project emphasizes specification-driven development and provides extensive documentation and templates to guide feature work, testing, and deployment.

Contributing

Contributions follow a structured workflow aligned with the specification-driven approach, including defining WHAT and WHY, planning, task breakdowns, and test-first development.

License

This project is licensed under the MIT License.

Available tools

AHK_Smart_Orchestrator

Intelligently orchestrates file operations to minimize redundant tool calls, chaining detect → analyze → read → edit with smart caching.

AHK_Run

Execute AutoHotkey scripts with optional window detection and timeout handling.

AHK_Diagnostics

Validate code syntax and enforce coding standards with detailed error reporting.

AHK_Analyze

Perform comprehensive script analysis with contextual documentation and usage insights.

AHK_File_View

View file contents and metadata without modifying the original file.

AHK_File_Edit_Diff

Edit files and provide diff-based changes for review.

AHK_Hotkey_Manager

Assist with hotkey definitions and conflict detection.

Clipboard_Prompt

Clipboard-related prompts for manipulation and analysis.

Snippet_Manager

Store and retrieve text snippets for quick insertion.

Link_Manager

Validate and open URLs, with integration to browsers.

File_System_Watcher

Watch directories for changes and trigger callbacks.

CPU_Monitor

Display CPU usage insights for running tools.