Skip to content
MCP server

Telegram MCP

Telegram MCP server for messages, chats and media, in bot or user-account mode

Runs locallyStatus and history
Install
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-telegram

Add 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.

How AIPoweredBot checks servers