AutoHotkey v2 MCP 服务器

一个用于 AutoHotkey v2 开发的 TypeScript MCP 服务器。它为 Claude Desktop 等 MCP 客户端提供脚本分析、文件操作、文档搜索和脚本执行工具。

架构

Related MCP server: Hotkeyless AHK MCP

亮点

• 25+ 个用于 AutoHotkey 工作流的 AHK_* 工具

• 聚焦文件发现和活动文件感知操作

• 带进程跟踪和窗口检测的脚本执行

• 本地 AutoHotkey 验证和诊断工具

• 内置 AutoHotkey 文档和提示/上下文辅助工具

• Stdio 和 Streamable HTTP 传输（有状态或无状态），以及传统 SSE 端点

• 可选的不记名令牌认证和 HTTP 模式的 DNS 重绑定保护

环境要求

• Node.js 18+

• npm

• AutoHotkey v2（用于运行/验证工具）

安装

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

运行

npm start

开发模式：

npm run dev

冒烟测试：

npm run smoke:mcp

HTTP 模式和环境变量

npm start 使用 stdio 协议（Claude Desktop）。要在 /mcp 上暴露 Streamable HTTP（以及传统 SSE 端点），请设置 PORT 或传入 --sse：

npm run start:sse

行为通过环境变量控制：

安全说明：工具面包含文件写入和进程执行。如果 HTTP 端口可被除本机以外的任何设备访问，请设置 AHK_MCP_AUTH_TOKEN（例如 openssl rand -hex 32）以及两个白名单——默认情况下端点接受所有请求。

有关会话流程、无状态模式详情和 cURL 示例，请参阅 docs/MCP_TRANSPORT_COMPATIBILITY.md。

Claude Desktop 配置

将此内容添加到 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"
      }
    }
  }
}

在 JSON 中使用绝对路径并转义反斜杠。

配置 AutoHotkey 路径和启动行为

使用 AHK_Config 设置可执行文件路径和非阻塞启动行为：

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

这由 AHK_Run（以及 AHK_Cloud_Validate 的路径解析）使用。

核心工具

• AHK_Smart_Orchestrator：简化多步骤编辑/分析工作流

• AHK_File_List、AHK_File_View、AHK_File_Edit：文件操作

• AHK_Analyze、AHK_Diagnostics：分析和诊断

• AHK_Run：执行脚本（等待、非等待、窗口检测）

• AHK_Cloud_Validate：基于本地执行的验证

• AHK_Doc_Search、AHK_Tools_Search：文档和工具查找

• AHK_Config：MCP 服务器配置

开发命令

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

文档

• docs/README.md

• docs/QUICK_START.md

• docs/QUICKREFERENCE.md

• docs/MCP_TRANSPORT_COMPATIBILITY.md

• docs/ARCHITECTURE_DIAGRAMS.md

• docs/RELEASE_NOTES.md

贡献

请参阅 CONTRIBUTING.md 和 AGENTS.md。

许可证

MIT。请参阅 LICENSE。