Telegram Bridge

A simple bridge to request human confirmation via Telegram from an MCP agent (like Antigravity).

Antigravity Configuration

To add this server to your Antigravity configuration (or any MCP client), use the following JSON block.

You need to replace:

• <ABSOLUTE_PATH> with the absolute path where you cloned this repository.
• <YOUR_VERCEL_URL> with your Vercel deployment URL (e.g., https://my-telegram-bot.vercel.app).

{
  "mcpServers": {
    "telegram-bot": {
      "command": "node",
      "args": ["<ABSOLUTE_PATH>/telegram-bot-mcp/mcp-server.js"],
      "env": {
        "VERCEL_URL": "https://<YOUR_VERCEL_URL>"
      }
    }
  }
}

Explanation

This script (mcp-server.js) acts as a local proxy. The agent communicates with it via stdio (standard), and the script makes HTTP requests to your Vercel backend, managing the question delivery and the polling (active waiting) for the response.

---

Architecture

1. Agent (Local) → calls ask_telegram_confirmation
2. Local Proxy (mcp-server.js) → calls POST /api/confirm on Vercel
3. Vercel → sends a message to the Telegram Bot
4. User → replies YES/NO on mobile
5. Telegram → calls the Webhook POST /api/webhook on Vercel
6. Vercel → saves the response in Redis (Upstash)
7. Local Proxy → receives the response by polling GET /api/confirm-status
8. Agent → receives the result "User replied: YES"

---

Installation and Deployment

1. Clone and Prepare

git clone https://github.com/aralroca/telegram-bot-mcp.git
cd telegram-bot-mcp
npm install

2. Configure Telegram

1. Talk to @BotFather to create a bot (/newbot).
2. Save the BOT_TOKEN.
3. Get your CHAT_ID (send a message to the bot and check https://api.telegram.org/bot<TOKEN>/getUpdates).

3. Deploy to Vercel

npm run deploy

Configure environment variables in Vercel:

• BOT_TOKEN: Your Telegram token.
• CHAT_ID: Your chat ID.
• ALLOWED_USER_ID: Your numeric user ID (for security).

Configure Upstash Redis (from Vercel Marketplace) for persistence.

4. Configure Webhook

Once deployed, register the Telegram webhook using your Vercel URL:

https://api.telegram.org/bot<BOT_TOKEN>/setWebhook?url=https://<YOUR_VERCEL_URL>/api/webhook

---

Troubleshooting and Tips

1. Vercel "401 Unauthorized"

If the agent receives a 401 error, it's likely due to Vercel Deployment Protection.

• Go to your Vercel Dashboard → Settings → Deployment Protection.
• Disable "Vercel Authentication".
• This allows the local MCP proxy and Telegram webhooks to reach your API.

2. Forbidden (403)

Make sure the ALLOWED_USER_ID in your Vercel environment variables matches your actual Telegram User ID. You can find your ID by sending a message to @userinfobot.

3. State Persistence (Redis)

This bridge uses Redis to keep track of questions while waiting for your reply.

• Use the Vercel Marketplace to add Upstash Redis.
• Ensure it's Connected to your project in the Storage tab.
• We support both REST protocol (UPSTASH_REDIS_REST_URL) and standard Redis protocol (REDIS_URL).
• Redeploy your project after connecting the storage.

4. Continuous Polling (Wait state)

If the agent stays in a "Waiting" state even after you reply "YES":

• Check if Redis is correctly initialized by visiting https://<YOUR_VERCEL_URL>/health.
• You should see "redis_initialized": true.

5. Stable URLs

Always use the Production Domain (e.g., my-project.vercel.app) in your Antigravity configuration VERCEL_URL environment variable. Using the specific deployment URL (the one with the hash) will stop working after your next deploy.

How to use with an Agent

To trigger the confirmation, you should invoke the MCP server by its name (defined in your configuration, e.g., telegram-bot) in your prompt. This helps the agent select the correct tool.

Example Prompts:

• "Use telegram-bot to ask for my confirmation before deleting any file."
• "Tell telegram-bot to send me a confirmation request to proceed with the deployment."

What happens next:

1. The agent will call the tool from the telegram-bot server.
2. You will receive a message from your bot on Telegram: Should I proceed? Reply: YES / NO.
3. The agent will stay in a "waiting" state while polling Vercel.
4. Once you reply YES or NO on your phone, the agent will receive the answer and continue its task.