# Telegram MCP

> Telegram MCP is an open-source MCP server for communication. Telegram MCP server for messages, chats and media, in bot or user-account mode. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted, telegram
- **Repository:** https://github.com/n24q02m/telegram
- **MCP Registry name:** io.github.n24q02m/telegram
- **Categories:** [communication](https://ai-powered.com/categories/communication)
- **Listing updated:** 2026-11-18

## About

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.

## Features

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

## Install

### Claude Code (Terminal)

```sh
claude mcp add telegram --env TELEGRAM_BOT_TOKEN='<TELEGRAM_BOT_TOKEN>' --env TELEGRAM_API_HASH='<TELEGRAM_API_HASH>' -- uvx n24q02m-telegram
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "telegram": {
      "command": "uvx",
      "args": [
        "n24q02m-telegram"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "<TELEGRAM_BOT_TOKEN>",
        "TELEGRAM_API_HASH": "<TELEGRAM_API_HASH>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "telegram": {
      "command": "uvx",
      "args": [
        "n24q02m-telegram"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "<TELEGRAM_BOT_TOKEN>",
        "TELEGRAM_API_HASH": "<TELEGRAM_API_HASH>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "telegram": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "n24q02m-telegram"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "<TELEGRAM_BOT_TOKEN>",
        "TELEGRAM_API_HASH": "<TELEGRAM_API_HASH>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "telegram": {
      "command": "uvx",
      "args": [
        "n24q02m-telegram"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "<TELEGRAM_BOT_TOKEN>",
        "TELEGRAM_API_HASH": "<TELEGRAM_API_HASH>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "telegram": {
      "command": "uvx",
      "args": [
        "n24q02m-telegram"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "<TELEGRAM_BOT_TOKEN>",
        "TELEGRAM_API_HASH": "<TELEGRAM_API_HASH>"
      }
    }
  }
}
```

## Tools

- `message`: Telegram messaging actions.
- `chat`: Telegram chat actions.
- `media`: Telegram media actions.
- `contact`: Telegram contact actions.
- `config`: Server configuration actions.
- `help`: Built-in documentation.

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

## Alternatives

- [TrendRadar](https://ai-powered.com/mcp/trendradar): TrendRadar is an open-source MCP server for communication.
- [Getmitra](https://ai-powered.com/mcp/getmitra): Getmitra is an MCP server for communication.
- [Discord](https://ai-powered.com/mcp/discord-2): Discord is a freemium MCP server for communication.
- [Zoom](https://ai-powered.com/mcp/zoom): Zoom is a freemium MCP server for communication.
- [Email Spam Tester](https://ai-powered.com/mcp/email-spam-tester): Email Spam Tester is a free MCP server for communication.
- [Slack_connect](https://ai-powered.com/mcp/slack-connect): Slack_connect is a freemium MCP server for communication.
- [Postmark](https://ai-powered.com/mcp/postmark): Postmark is a freemium MCP server for communication.
- [Gmail](https://ai-powered.com/mcp/gmail-5): Gmail is a freemium MCP server for communication.

---
Source: https://ai-powered.com/mcp/telegram-mcp-5
