Quickstart

From npm to a working ask in minutes.

1. Create a bot and configure

Run the interactive setup wizard. It validates your bot token, auto-detects your chat id, writes the config, and prints the MCP client entry to paste:

npx ping-a-human setup

The wizard walks you through:

Message @BotFather in Telegram, send /newbot, and copy the bot token.
Paste the token — the wizard verifies it and shows your bot's @username.
Send your new bot any message (e.g. "hi"), then press Enter — your chat_id is auto-detected.
The config is saved and an mcpServers snippet is printed.

2. Add the server to your MCP client

Add this to your MCP client config (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "ping-a-human": {
      "command": "npx",
      "args": ["-y", "ping-a-human"]
    }
  }
}

Restart the client. It will list notify_human and ask_human.

3. Use it from an agent

Notify when a job finishes: notify_human({ message: "Deploy finished ✅" }).
Ask with buttons: ask_human({ question: "Apply migration?", choices: ["Yes", "No"] }) — the human taps a button and the agent receives that value.
Ask an open question: ask_human({ question: "Release title?" }) — returns the free-text reply.

Local development

npm install
npm run build
node dist/index.js          # starts the stdio MCP server
node dist/index.js setup    # runs the setup wizard
npm test                    # runs the full test suite

← Introduction Tools →