alert-my-human

Let your agent notify you when a task finishes, a job fails, or it needs your attention. Send alerts through email, Slack, Telegram, SMS, or webhooks.

A small MCP server for personal automations. No database, queue, or background service. Bring your own provider credentials; hosting and notification providers may charge for usage.

Quick start (MCP server)

1. Choose a channel

Configure just one to begin. Leave the other variables unset.

Set AUTH_API_KEY to a long random secret, separate from your provider credentials:

node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"

2. Run the server

Vercel — no local server to keep running:

Enter AUTH_API_KEY when prompted. Add your channel variables in the project's environment settings for Production, then redeploy so they take effect. Your endpoint is https://<your-domain>/api/mcp.

Locally — Node.js 24 and pnpm 12.9.1:

git clone https://github.com/LMol-4/alert-my-human.git
cd alert-my-human
pnpm install --frozen-lockfile

Copy .env.example to .env, set your key and channel variables, then run pnpm dev. The endpoint is http://localhost:3000/api/mcp. Keep the process running; a remote client cannot reach your computer's localhost.

3. Connect your agent

Use an MCP client that supports HTTP servers with custom headers. For clients using mcpServers configuration:

{
  "mcpServers": {
    "alert-my-human": {
      "type": "http",
      "url": "https://<your-domain>/api/mcp",
      "headers": {
        "Authorization": "Bearer <AUTH_API_KEY>"
      }
    }
  }
}

Replace both placeholders; use the localhost URL for a local client. Keep the real token out of committed client configuration. Claude Code configuration guidance.

4. Send your first alert

Ask your agent: “Use alert-my-human to list my channels, then send a test alert through one of them.”

list_channels takes no arguments and also reports partly configured channels. Example send_alert arguments, if email is configured:

{
  "channels": ["email"],
  "title": "It works!",
  "message": "Your agent can reach you."
}

Required: channels, title (up to 250 characters), and message (up to 4000). Optional: severity (info, success, warning, error; default info), context (up to 20 string key/value pairs), and idempotencyKey (reuse it when retrying the same alert).

Results

Each channel gets its own result:

{ "destination": "telegram", "outcome": "accepted", "attempts": 1, "durationMs": 212, "providerId": "42" }
{ "destination": "e

... [View full README on GitHub](https://github.com/LMol-4/alert-my-human#readme)