How do I use telegram-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@telegram-mcp Send a status update to the dev team about the build progress." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

telegram-mcp

Q: Which integrations are available for this server?

Allows AI agents to send messages, photos, documents, polls, progress updates, and receive user responses via Telegram, enabling bidirectional communication and workflow automation.

by Abol1644

Overview Schema Related Servers Score Discussions

TypeScript

Remote

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

Related MCP server: mcp-telegram

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
The Chat ID of your target Telegram chat(s) (use @userinfobot to find)

Installation

Option 1: npm / pnpm (standalone)

# 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

# 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

# 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:

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:

{
  "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:

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

On timeout:

{
  "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

// 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

# 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

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

# 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:

Builder stage — Installs dev dependencies, compiles TypeScript
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

This server cannot be installed

license - not found

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Abol1644/telegram-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server