HeadsUp — Telegram for your local model

Give your AI a line to your phone. It pings you on Telegram when a task finishes — and you can reply from your phone to steer it mid-task, without touching the computer.

It's a small MCP server for LM Studio: one Node process, four tools, no cloud.

What you get

• Notifications — a push on your phone when the AI finishes something, with a ✅ / ℹ️ / ⚠️ / ❌ header

• Two-way — the AI can ask you a question on Telegram and wait for your answer, so you can decide from anywhere

Related MCP server: Telegram MCP Server

Setup

You'll need Node.js, LM Studio, and a Telegram account.

1. Create a bot

1. In Telegram, message @BotFather

2. Send /newbot and follow the prompts

3. Copy the API token it gives you

2. Get your chat ID

1. Message @userinfobot in Telegram

2. Copy the Id number from its reply

3. Start the bot

Search for your bot in Telegram and tap Start — the bot can't message you until you do.

4. Install

From the folder that contains index.js:

npm install

5. Configure

Add this to LM Studio's MCP settings (mcp.json). Replace the path, chat ID, and token with your own:

{
  "mcpServers": {
    "telegram-notifier": {
      "command": "node",
      "args": ["/path/to/HeadsUp-MCP/index.js"],
      "env": {
        "TELEGRAM_CHAT_ID": "YOUR_CHAT_ID",
        "TELEGRAM_BOT_TOKEN": "YOUR_BOT_TOKEN"
      }
    }
  }
}

• Token missing? The server logs a clear error and exits — nothing fails silently.

• More than one device? Put several chat IDs in, comma-separated — "TELEGRAM_CHAT_ID": "123456, 789012" — and every notification goes to all of them.

6. Restart LM Studio

Fully quit and reopen it so it loads the new server.

Using it

Just ask:

"Write a Python script to sort a list. Ping me on Telegram when you're done."

You'll get a push the moment it finishes.

Notification options

The send_telegram_notification tool takes:

Long messages split themselves to fit Telegram's limits, and if your text trips up Telegram's Markdown the message is retried plain instead of failing.

Asking you back

The bot can also ask and wait:

For example:

"Which database should I use for this?" → the AI asks on your phone: "SQLite or Postgres?" → you tap SQLite from wherever you are → the AI keeps going with SQLite

A couple of things worth knowing:

• Replies are kept in memory for the current conversation — if LM Studio restarts, the queue clears (your messages are still in your Telegram history, obviously).

• It's guarded against runaway loops — the bot won't keep asking or re-asking on its own.

Testing

npm test            # offline end-to-end suite (mocked Bot API — nothing touches your phone)
node e2e-test.mjs   # LIVE test: really sends to your phone — set TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID first

Sharing it

Hand someone index.js, package.json, and this README. They run npm install, grab their own chat ID from @userinfobot, start the bot, and drop their chat ID and token into their mcp.json. Everyone uses their own token — nothing is ever hardcoded.

Troubleshooting

License

MIT