@tim0_12432/hotkeyless-ahk-mcp-server

Hotkeyless AHK MCP and Skills

This repository provides:

• A TypeScript MCP server that wraps the Hotkeyless AHK HTTP API.
• Reusable skill documents for OpenCode, Claude, and generic agent runtimes.
• Practical examples for desktop automation scenarios.

Workspace layout

packages/
  mcp-server/   # Node MCP server package
  skills/       # Agent skill documents
examples/       # End-to-end usage examples

• MCP server

• Quick start
• Hotkeyless AHK API contract
• Configuration

• Agent skills

• Quick start

MCP server

Quick start

OpenCode

opencode.json:

{
  ...
  "mcp": {
    ...
    "hotkeyless-ahk": {
      "type": "local",
      "command": ["npx", "-y", "@tim0_12432/hotkeyless-ahk-mcp-server"],
      "enabled": true,
      "environment": {
          "BLACKLIST": "shutdown,restart,kill"
          ...
      }
    }
  },
  ...
}

ClaudeCode

.mcp.json:

{
  "mcpServers": {
    ...
    "hotkeyless-ahk": {
      "command": "npx",
      "args": ["-y", "@tim0_12432/hotkeyless-ahk-mcp-server"],
      "env": {
        "BLACKLIST": "shutdown,restart,kill"
        ...
      }
    }
  }
}

Github Copilot

mcp-config.json:

{
  ...
  "mcpServers": {
    ...
    "hotkeyless-ahk": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@tim0_12432/hotkeyless-ahk-mcp-server"],
      "env": {
        "BLACKLIST": "shutdown,restart,kill"
          ...
      },
      "tools": ["*"]
    }
  },
  ...
}

Build from source

Follow instructions here.

1. Build server

bun install
bun run build

npm should also work without problems!

2. Setup your harness

OpenCode

opencode.json:

{
  ...
  "mcp": {
    ...
    "hotkeyless-ahk": {
      "type": "local",
      "command": ["node", "<absolute path to the built files>/mcp-server/dist/index.js"],
      "enabled": true,
      "environment": {
          "BLACKLIST": "shutdown,restart,kill"
          ...
      }
    }
  },
  ...
}

ClaudeCode

.mcp.json:

{
  "mcpServers": {
    ...
    "hotkeyless-ahk": {
      "command": "node",
      "args": ["<absolute path to the built files>/mcp-server/dist/index.js"],
      "env": {
        "BLACKLIST": "shutdown,restart,kill"
        ...
      }
    }
  }
}

Github Copilot

mcp-config.json:

{
  ...
  "mcpServers": {
    ...
    "hotkeyless-ahk": {
      "type": "local",
      "command": "node",
      "args": ["<absolute path to the built files>/mcp-server/dist/index.js"],
      "env": {
        "BLACKLIST": "shutdown,restart,kill"
          ...
      },
      "tools": ["*"]
    }
  },
  ...
}

Hotkeyless AHK API contract

• GET /list returns JSON array of { command: string, note: string }
• GET /send/<command> accepts query parameters

Configuration

Default config is at mcp-server/dist/infrastructure/config/config.ts.

Environment overrides:

Parameter override	What it does	Default
BASE_URL	Adress of the Hotkeyless AHK server	http://localhost:42800
TIMEOUT_MS	Timeout milliseconds for each request	4000
BLACKLIST	A list of commands to avoid being called	[]
CACHE_TTL_MS	Cache lifetime for command list in milliseconds	5000
ENDPOINT_LIST	Endpoint address of the command list	/list
ENDPOINT_TRIGGER	Endpoint address for invoking commands	/send

Agent Skills

Quick start

OpenCode

• Copy the ./skills/.opencode/... folders to

• .opencode/skills for project specific skill setup
• %USERPROFILE%/.config/opencode/skills for global setup

• You can adjust AGENTS.md, custom subagents or custom commands to reference the skills
• Restart your OpenCode (CLI or Desktop)
• When asking the agent to use the "hotkeyless AHK skills" it should now use the skill guide

ClaudeCode

• Copy the ./skills/.claude/... folders to

• .claude/skills for project specific skill setup
• %USERPROFILE%/.config/claude-code/skills for global setup

• You can adjust CLAUDE.md, custom subagents or custom commands to reference the skills
• Restart your Claude Code
• When asking the agent to use the "hotkeyless AHK skills" it should now use the skill guide

Github Copilot

• Copy the ./skills/.claude/... folders to

• .claude/skills for project specific skill setup
• %USERPROFILE%/.config/claude-code/skills for global setup

• You can adjust AGENTS.md, custom subagents or custom commands to reference the skills
• Restart your Claude Code
• When asking the agent to use the "hotkeyless AHK skills" it should now use the skill guide

License

MIT