┌─────────────────┐     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)

# 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

# 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

# Development mode (with hot reload)
npm run dev

# Production mode
npm start

# With Docker
docker compose up

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

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

{
  "received": true,
  "text": "User's reply message",
  "messageId": 42
}

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

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)    │                        │

// 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."
  });
}

# 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

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

npm test

# 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