# Telegram Confirmation MCP 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`).
```json
{
"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
```bash
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
```bash
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.
