# telegram-mcp 🤖✉️

**MCP (Model Context Protocol) server for Telegram Bot API integration.**  
Enables AI agents to send messages, photos, documents, polls, progress updates, and receive user responses via Telegram — all with persistent storage, rate limiting, and robust error handling.

---

## Features

- ✅ **10 MCP Tools** — send_message, send_photo, send_document, send_progress, send_todo_update, send_error_alert, ask_user, wait_for_response, create_poll, send_daily_report
- ✅ **Bidirectional Communication** — AI agents can pause, ask questions, wait for Telegram replies, and resume workflows based on user responses
- ✅ **Multi-Chat Support** — Configure one or many Telegram chats/groups/channels
- ✅ **MarkdownV2 Formatting** — Rich text with bold, italic, code blocks, links, tables, progress bars
- ✅ **SQLite Persistence** — Conversation history, pending response tracking, message logs
- ✅ **Rate Limiting** — Token-bucket algorithm respects Telegram's API limits
- ✅ **Retry with Exponential Backoff** — Auto-retries failed API calls
- ✅ **Comprehensive Logging** — Structured logs with levels (debug/info/warn/error)
- ✅ **Type-Safe** — Full TypeScript with Zod schemas for all tool inputs
- ✅ **Docker Support** — Multi-stage Dockerfile + docker-compose
- ✅ **Environment Config** — All settings via environment variables with `.env.example`
- ✅ **Polling-Based Updates** — No webhook needed; polls Telegram for new messages

---

## Architecture

```
┌─────────────────┐     stdio      ┌──────────────────────────┐
│  AI Agent /      │ ◄──────────► │     telegram-mcp          │
│  MCP Client      │               │                          │
└─────────────────┘               │  ┌───────────────────┐   │
                                   │  │  MCP Tools Layer  │   │
                                   │  │  (Zod schemas)    │   │
                                   │  └────────┬──────────┘   │
                                   │           │               │
                                   │  ┌────────▼──────────┐   │
                                   │  │  Telegram Client   │   │
                                   │  │  (retry + rate     │   │
                                   │  │   limiting)        │   │
                                   │  └────────┬──────────┘   │
                                   │           │               │
                                   │  ┌────────▼──────────┐   │
                                   │  │  Update Poller     │   │
                                   │  │  (getUpdates loop) │   │
                                   │  └────────┬──────────┘   │
                                   │           │               │
                                   │  ┌────────▼──────────┐   │
                                   │  │  SQLite Storage    │   │
                                   │  │  (better-sqlite3)  │   │
                                   │  └───────────────────┘   │
                                   └──────────────────────────┘
                                              │
                                    Telegram Bot API
                                              │
                                         Telegram
                                        (Users/Chats)
```

---

## Prerequisites

- **Node.js** ≥ 22 (or Docker)
- A **Telegram Bot Token** from [@BotFather](https://t.me/botfather)
- The **Chat ID** of your target Telegram chat(s) (use [@userinfobot](https://t.me/userinfobot) to find)

---

## Installation

### Option 1: npm / pnpm (standalone)

```bash
# Clone or create the project directory
cd telegram-mcp

# Install dependencies
npm install

# Build TypeScript
npm run build

# Copy and edit environment file
cp .env.example .env
# Edit .env with your BOT_TOKEN and CHAT_ID
```

### Option 2: Docker

```bash
# Build the image
docker build -t telegram-mcp .

# Or use docker-compose
cp .env.example .env
# Edit .env with your BOT_TOKEN and CHAT_ID
docker compose up -d
```

---

## Configuration

All configuration is via environment variables (defined in `.env`):

| Variable | Required | Default | Description |
|---|---|---|---|
| `BOT_TOKEN` | ✅ | — | Telegram Bot API token from @BotFather |
| `CHAT_ID` | ✅ | — | Comma-separated chat IDs (e.g., `123456789,-987654321`) |
| `OWNER_ID` | ❌ | — | Bot owner's Telegram user ID |
| `DB_PATH` | ❌ | `./data/telegram-mcp.db` | SQLite database file path |
| `LOG_LEVEL` | ❌ | `info` | Log level: `debug`, `info`, `warn`, `error` |
| `POLL_INTERVAL_MS` | ❌ | `2000` | Polling interval for message updates (ms) |
| `RESPONSE_TIMEOUT_SEC` | ❌ | `300` | Default timeout for `wait_for_response` (seconds) |
| `RESPONSE_POLL_INTERVAL_MS` | ❌ | `500` | Poll interval when waiting for a response (ms) |
| `RATE_LIMIT_RPS` | ❌ | `30` | Telegram API rate limit (requests per second) |
| `MAX_RETRIES` | ❌ | `3` | Maximum retries for failed API calls |

---

## Usage

### Running the Server

```bash
# Development mode (with hot reload)
npm run dev

# Production mode
npm start

# With Docker
docker compose up
```

The server starts an MCP service over **stdio**, which is automatically used by MCP-compatible clients.  
Configure your AI agent or MCP client to launch:

```bash
node /path/to/telegram-mcp/dist/index.js
```

### MCP Client Configuration

If using Claude Desktop or another MCP client, add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["/absolute/path/to/telegram-mcp/dist/index.js"],
      "env": {
        "BOT_TOKEN": "your_bot_token",
        "CHAT_ID": "your_chat_id"
      }
    }
  }
}
```

---

## Tools

### `send_message`

Send a text message to one or all configured chats.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `text` | string | ✅ | Message content (MarkdownV2) |
| `chat_id` | string | ❌ | Specific chat ID; omit to broadcast |
| `parse_mode` | enum | ❌ | `MarkdownV2` (default), `HTML`, `Markdown` |
| `disable_web_page_preview` | boolean | ❌ | Disable link previews |
| `disable_notification` | boolean | ❌ | Send silently |

### `send_photo`

Send a photo (by URL or Telegram file_id).

| Parameter | Type | Required | Description |
|---|---|---|---|
| `photo` | string | ✅ | URL or file_id |
| `caption` | string | ❌ | Optional caption |
| `chat_id` | string | ❌ | Specific chat ID |
| `parse_mode` | enum | ❌ | `MarkdownV2`, `HTML` |

### `send_document`

Send a document (by URL or file_id).

| Parameter | Type | Required | Description |
|---|---|---|---|
| `document` | string | ✅ | URL or file_id |
| `caption` | string | ❌ | Optional caption |
| `chat_id` | string | ❌ | Specific chat ID |
| `filename` | string | ❌ | Display name |

### `send_progress`

Send a visual progress bar.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `title` | string | ✅ | Progress title |
| `current` | number | ✅ | Current value |
| `total` | number | ✅ | Total value |
| `status_text` | string | ❌ | Optional status |
| `chat_id` | string | ❌ | Specific chat ID |

### `send_todo_update`

Notify about a todo item status change.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `action` | enum | ✅ | `created`, `updated`, `completed`, `deleted` |
| `title` | string | ✅ | Todo title |
| `description` | string | ❌ | Optional description |
| `status` | string | ❌ | e.g., `in progress`, `done` |
| `priority` | enum | ❌ | `low`, `medium`, `high`, `urgent` |
| `chat_id` | string | ❌ | Specific chat ID |

### `send_error_alert`

Send a structured error notification.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `title` | string | ✅ | Error title |
| `description` | string | ✅ | Error details |
| `stack` | string | ❌ | Stack trace |
| `metadata` | object | ❌ | Key-value pairs |
| `chat_id` | string | ❌ | Specific chat ID |

### `create_poll`

Create and send a poll.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `question` | string | ✅ | Poll question |
| `options` | string[] | ✅ | 2–10 options |
| `is_anonymous` | boolean | ❌ | Default: true |
| `allows_multiple_answers` | boolean | ❌ | Default: false |
| `type` | enum | ❌ | `regular`, `quiz` |
| `correct_option_id` | number | ❌ | For quiz polls |
| `explanation` | string | ❌ | For quiz polls |
| `open_period` | number | ❌ | Auto-close seconds |
| `chat_id` | string | ❌ | Specific chat ID |

### `send_daily_report`

Send a structured daily summary.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `date` | string | ❌ | ISO date (defaults to today) |
| `title` | string | ✅ | Report title |
| `sections` | array | ✅ | `[{heading, content}]` |
| `footer` | string | ❌ | Optional footer |
| `chat_id` | string | ❌ | Specific chat ID |

### `ask_user`

Send a question and create a pending response slot. Returns a `response_id`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `question` | string | ✅ | Question text |
| `chat_id` | string | ❌ | Specific chat ID |
| `timeout_seconds` | number | ❌ | Override default timeout |

**Returns:** `response_id` string (pass to `wait_for_response`)

### `wait_for_response`

Block until the user replies to a previously asked question.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `response_id` | string | ✅ | ID from `ask_user` |
| `timeout_seconds` | number | ❌ | Timeout override |
| `chat_id` | string | ❌ | Narrow chat scope |

**Returns:**
```json
{
  "received": true,
  "text": "User's reply message",
  "messageId": 42
}
```

On timeout:
```json
{
  "received": false,
  "error": "Timeout: No response received within the allowed time."
}
```

---

## Two-Phase Agent Workflow (ask → wait → resume)

The most powerful feature is the ability for an AI agent to **pause execution**, **ask a question** via Telegram, **wait** for the user's reply, and **resume** the workflow based on the response.

### Flow

```
Agent                    telegram-mcp              Telegram User
  │                          │                        │
  │── ask_user({question}) ──►─────────── message ────►│
  │◀── { response_id } ──────│                        │
  │                          │                        │
  │── wait_for_response({    │                        │
  │     response_id }) ──────►                        │
  │                          │                        │
  │                          │◄──── reply ────────────│
  │◀── { received:true,     │                        │
  │      text:"..." } ──────│                        │
  │                          │                        │
  │ (resumes logic based    │                        │
  │  on user's response)    │                        │
```

### Example Agent Script

```typescript
// Phase 1: Ask the user
const { response_id } = await mcp.callTool("ask_user", {
  question: "Which report should I generate? (daily/weekly/monthly)"
});

// Phase 2: Wait for their response (blocks up to 5 minutes)
const result = await mcp.callTool("wait_for_response", {
  response_id: response_id,
  timeout_seconds: 300
});

if (result.received) {
  const userChoice = result.text.toLowerCase();
  if (userChoice.includes("daily")) {
    await generateDailyReport();
  } else if (userChoice.includes("weekly")) {
    await generateWeeklyReport();
  }
  await mcp.callTool("send_message", {
    text: `✅ Generating ${userChoice} report...`
  });
} else {
  await mcp.callTool("send_error_alert", {
    title: "No Response",
    description: "User did not respond within the timeout period."
  });
}
```

---

## Development

```bash
# Install dependencies
npm install

# Run in development mode (with hot reload)
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Build for production
npm run build

# Lint (if configured)
npm run lint
```

### Project Structure

```
telegram-mcp/
├── src/
│   ├── index.ts                 # Entry point — starts MCP server + polling
│   ├── config.ts                # Environment variable validation (Zod)
│   ├── logger.ts                # Structured logging
│   ├── types.ts                 # TypeScript interfaces
│   ├── telegram/
│   │   ├── client.ts            # Telegram Bot API client (retry, rate limit)
│   │   └── formatter.ts         # MarkdownV2 formatting utilities
│   ├── storage/
│   │   └── db.ts                # SQLite database (conversations, pending)
│   ├── handlers/
│   │   └── updates.ts           # Telegram update polling
│   └── mcp/
│       └── tools.ts             # All MCP tool definitions + response handler
├── tests/
│   └── telegram-mcp.test.ts     # Vitest unit tests
├── Dockerfile                   # Multi-stage Docker build
├── docker-compose.yml           # Docker Compose setup
├── .env.example                 # Environment template
├── vitest.config.ts             # Test configuration
├── tsconfig.json                # TypeScript configuration
└── package.json
```

---

## Testing

```bash
npm test
```

Tests cover:
- MarkdownV2 escaping and formatting
- Structured message builders (errors, todos, reports, polls)
- Database CRUD operations (in-memory SQLite)
- Config validation logic
- Response ID generation

---

## Error Handling & Reliability

- **Exponential backoff** — Failed Telegram API calls retry with `1s → 2s → 4s` delays (configurable)
- **Rate limiting** — Token-bucket algorithm prevents hitting Telegram's rate limits
- **Graceful shutdown** — Cleanly closes database and stops polling on SIGINT/SIGTERM
- **Uncaught exception handling** — Logs fatal errors before exiting
- **Input validation** — All tool inputs validated with Zod schemas

---

## Database

The server uses **SQLite** (via `better-sqlite3`) for persistence:

- **conversations** — Full chat history (user + agent messages)
- **pending_responses** — Active `ask_user` / `wait_for_response` requests
- **messages_log** — Auditable log of all sent/received messages

The database file is stored at `DB_PATH` (default: `./data/telegram-mcp.db`).

---

## Docker

### Build & Run

```bash
# Build
docker build -t telegram-mcp .

# Run with .env file
docker run --env-file .env -v telegram-mcp-data:/app/data telegram-mcp

# Or use docker-compose
docker compose up -d
```

### Multi-Stage Build

The Dockerfile uses a multi-stage build:
1. **Builder** stage — Installs dev dependencies, compiles TypeScript
2. **Production** stage — Minimal image with only runtime dependencies

---

## Security

- **Bot Token** — Keep your `BOT_TOKEN` secret. Never commit it to version control.
- **Chat IDs** — Restrict which chats the bot listens to via `CHAT_ID`.
- **Input Validation** — All tool inputs are validated with Zod schemas.
- **No Webhooks** — Uses polling instead, avoiding the need for a public HTTPS endpoint.

---

## License

MIT

---

## Contributing

Contributions are welcome! Please open an issue or PR for:

- Additional Telegram API features
- Improved formatting utilities
- Enhanced response matching (e.g., reply chains)
- Webhook support
- Multi-language support