H

Hotkeyless Ahk Mcp

Hotkeyless Ahk Mcp

Local

github.com/tim0-12432Productivity2Updated 11w ago

About Hotkeyless Ahk Mcp

Hotkeyless Ahk Mcp is a TypeScript MCP server and set of reusable agent skills for controlling a computer through the Hotkeyless AHK HTTP API. It includes configuration for command access and examples for desktop automation.

Key features

01Wraps the Hotkeyless AHK HTTP API
02Reusable agent skill documents
03Command-list caching
04Configurable command blacklist
05Desktop automation examples

Use cases

01Let an agent invoke configured hotkeys
02Prevent selected commands from being called
03Use skill guides in OpenCode or Claude

MCP support

The MCP server exposes Hotkeyless AHK API commands to MCP clients. It retrieves commands from `/list` and triggers them through `/send`.

#ahk #hotkeyless-ahk #hotkeys #auto-hotkey

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config

{
  "mcpServers": {
    "HotkeylessAHK-mcp-skill": {
      "command": "npx",
      "args": [
        "-y",
        "@tim0_12432/hotkeyless-ahk-mcp-server"
      ],
      "env": {
        "BASE_URL": "<BASE_URL>",
        "TIMEOUT_MS": "<TIMEOUT_MS>",
        "BLACKLIST": "<BLACKLIST>",
        "CACHE_TTL_MS": "<CACHE_TTL_MS>",
        "ENDPOINT_LIST": "<ENDPOINT_LIST>",
        "ENDPOINT_TRIGGER": "<ENDPOINT_TRIGGER>"
      }
    }
  }
}

Run commandnpx -y @tim0_12432/hotkeyless-ahk-mcp-server

Environment variables to set

BASE_URLThe base URL of the Hotkeyless AHK HTTP server.

TIMEOUT_MSThe timeout in milliseconds for requests to the server.

BLACKLISTA comma-separated list of blacklisted commands.

CACHE_TTL_MSThe time-to-live in milliseconds for cached responses.

ENDPOINT_LISTThe default endpoint path for listing commands.

ENDPOINT_TRIGGERThe default endpoint path for triggering commands.

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages

npm@tim0_12432/hotkeyless-ahk-mcp-server1.0.8stdio

Tools

4

Saved tool list · updated 3w ago

Parameter	Type	Required	Description
refresh	boolean	No	Set true to bypass cache and force a fresh /list request.

Details

From the project README

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

Comments

Markdown supported

Sign in to comment

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

Read the getting-started guide

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.