Telegram MCP
Telegram MCP server for messages, chats and media, in bot or user-account mode
- Pricing
- Open source
- Platforms
- CLI, self-hosted, telegram
- Runs
- Locally
- Version
- 4.25.0
- Listing updated
- today
Similar MCP servers
About Telegram MCP
Telegram MCP is an open-source MCP server for communication. It runs locally on your machine and is started by your AI client.
This server talks to Telegram in two ways. Bot mode uses the Bot API with a token from BotFather, while user mode signs in with a phone number over MTProto (Telethon), so an agent can act as an ordinary account. The mode is picked automatically from whichever credentials are set.
It keeps the tool surface small: six tools (message, chat, media, contact, config, help) that each take an action argument. Credentials stay on the machine running the server, set through a telegram auth command that handles bot tokens or phone, one-time code and 2FA.
By default it runs over stdio, and an HTTP mode supports loopback-only access, one bearer token or per-user tokens. The README lists protections such as SSRF and path traversal checks, sanitised errors and boundary tags around Telegram content to resist prompt injection. It is Apache-licensed and ships on PyPI and Docker.
Install
Run in a terminal
claude mcp add telegram --env TELEGRAM_BOT_TOKEN='<TELEGRAM_BOT_TOKEN>' --env TELEGRAM_API_HASH='<TELEGRAM_API_HASH>' -- uvx n24q02m-telegramAdd to claude_desktop_config.json
{
"mcpServers": {
"telegram": {
"command": "uvx",
"args": [
"n24q02m-telegram"
],
"env": {
"TELEGRAM_BOT_TOKEN": "<TELEGRAM_BOT_TOKEN>",
"TELEGRAM_API_HASH": "<TELEGRAM_API_HASH>"
}
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"telegram": {
"command": "uvx",
"args": [
"n24q02m-telegram"
],
"env": {
"TELEGRAM_BOT_TOKEN": "<TELEGRAM_BOT_TOKEN>",
"TELEGRAM_API_HASH": "<TELEGRAM_API_HASH>"
}
}
}
}Add to .vscode/mcp.json
{
"servers": {
"telegram": {
"type": "stdio",
"command": "uvx",
"args": [
"n24q02m-telegram"
],
"env": {
"TELEGRAM_BOT_TOKEN": "<TELEGRAM_BOT_TOKEN>",
"TELEGRAM_API_HASH": "<TELEGRAM_API_HASH>"
}
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"telegram": {
"command": "uvx",
"args": [
"n24q02m-telegram"
],
"env": {
"TELEGRAM_BOT_TOKEN": "<TELEGRAM_BOT_TOKEN>",
"TELEGRAM_API_HASH": "<TELEGRAM_API_HASH>"
}
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"telegram": {
"command": "uvx",
"args": [
"n24q02m-telegram"
],
"env": {
"TELEGRAM_BOT_TOKEN": "<TELEGRAM_BOT_TOKEN>",
"TELEGRAM_API_HASH": "<TELEGRAM_API_HASH>"
}
}
}
}Using several servers? Build one config file with the MCP config generator.
Configuration
TELEGRAM_BOT_TOKENTelegram bot token from @BotFather (for bot mode)TELEGRAM_API_IDTelegram API ID from my.telegram.org (for user mode)TELEGRAM_API_HASHTelegram API hash from my.telegram.org (for user mode)TELEGRAM_BOT_TOKENTelegram bot token from @BotFather (for bot mode)
Tools this server provides (6)
Taken from the project documentation; the running server may differ.
- message
- Telegram messaging actions.
- chat
- Telegram chat actions.
- media
- Telegram media actions.
- contact
- Telegram contact actions.
- config
- Server configuration actions.
- help
- Built-in documentation.
What it does
- Bot and user modes
- Use a BotFather token, or sign in as a user with phone, one-time code and 2FA.
- Six action-based tools
- message, chat, media, contact, config and help each dispatch by action.
- Local CLI auth
- `telegram auth` stores credentials on the machine running the server.
- Stdio or HTTP
- HTTP can run unauthenticated on loopback, with one bearer token, or per-user tokens.
- Tool annotations
- Each tool declares read-only, destructive, idempotent and open-world hints.
- Injection hardening
- Telegram content is wrapped in boundary tags, with SSRF and path traversal checks.
Good for
- Let an agent read and send messages in Telegram chats
- Run a bot that replies to messages using an LLM
- Fetch media and contact details from a user account
- Summarise a busy group chat for a daily digest
Pricing
Open source
Apache-2.0 licensed; free to self-host
More servers for the same service
Telegram MCP FAQ
Which install options exist?
Install with uvx n24q02m-telegram, as a Docker image n24q02m/telegram, or as a Claude Code plugin from the author's marketplace.
What credentials are needed?
Bot mode needs TELEGRAM_BOT_TOKEN from BotFather. User mode needs a phone number, and an optional API ID and hash.
What licence is it under?
The README shows an Apache 2.0 licence badge.
Was it renamed?
Yes. The package was formerly better-telegram-mcp, and the old command stays as an alias.
Is Telegram MCP free?
Yes. Telegram MCP is open source, so you can use and self-host it for free.
How do I add Telegram MCP to Claude Code?
Run this command in your terminal: claude mcp add telegram --env TELEGRAM_BOT_TOKEN='<TELEGRAM_BOT_TOKEN>' --env TELEGRAM_API_HASH='<TELEGRAM_API_HASH>' -- uvx n24q02m-telegram
What are the best alternatives to Telegram MCP?
The closest alternatives to Telegram MCP are TrendRadar, Getmitra, Discord, Zoom and Email Spam Tester.
Where this comes from
- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

