# Telegram

> Send messages and read channel history from a Telegram bot in an agent.

[Canonical HTML page](https://top-mcps.com/mcp/telegram) · [server.json](https://top-mcps.com/mcp/telegram.json) · [methodology](https://top-mcps.com/about/methodology)

## Install

### Claude Desktop — `claude_desktop_config.json`

Paste under mcpServers. Fully quit and reopen Claude after editing.

```json
{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": [
        "-y",
        "telegram-mcp"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "${TELEGRAM_BOT_TOKEN}"
      }
    }
  }
}
```

### Claude Code — `CLI or .mcp.json`

Run from your repo. Commit .mcp.json to share with your team.

```shell
# export TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
claude mcp add telegram -- npx -y telegram-mcp
```

### Cursor — `.cursor/mcp.json`

Global path: ~/.cursor/mcp.json. Reload window after editing.

```json
{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": [
        "-y",
        "telegram-mcp"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "${TELEGRAM_BOT_TOKEN}"
      }
    }
  }
}
```

### VS Code — `.vscode/mcp.json`

VS Code uses the "servers" key (not "mcpServers").

```jsonc
{
  "servers": {
    "telegram": {
      "command": "npx",
      "args": [
        "-y",
        "telegram-mcp"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "${TELEGRAM_BOT_TOKEN}"
      }
    }
  }
}
```

### Windsurf — `~/.codeium/windsurf/mcp_config.json`

Open via Cascade → hammer icon → Configure.

```json
{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": [
        "-y",
        "telegram-mcp"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "${TELEGRAM_BOT_TOKEN}"
      }
    }
  }
}
```

### Cline — `cline_mcp_settings.json`

Open via the Cline sidebar → MCP Servers → Edit.

```json
{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": [
        "-y",
        "telegram-mcp"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "${TELEGRAM_BOT_TOKEN}"
      }
    }
  }
}
```

### Continue — `~/.continue/config.json`

Continue uses modelContextProtocolServers with a transport block.

```json
{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": [
            "-y",
            "telegram-mcp"
          ],
          "env": {
            "TELEGRAM_BOT_TOKEN": "${TELEGRAM_BOT_TOKEN}"
          }
        }
      }
    ]
  }
}
```

### Codex CLI — `~/.codex/config.toml`

Codex uses TOML. Each server is a [mcp_servers.<name>] subtable.

```shell
# ~/.codex/config.toml
[mcp_servers.telegram]
command = "npx"
args = [
  "-y",
  "telegram-mcp",
]
env = { TELEGRAM_BOT_TOKEN = "${TELEGRAM_BOT_TOKEN}" }
```

### Zed — `~/.config/zed/settings.json`

Zed calls them "context_servers". Settings live-reload on save.

```jsonc
{
  "context_servers": {
    "telegram": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "telegram-mcp"
        ]
      },
      "env": {
        "TELEGRAM_BOT_TOKEN": "${TELEGRAM_BOT_TOKEN}"
      }
    }
  }
}
```

### ChatGPT — `ChatGPT → Apps directory`

Telegram doesn't ship a hosted HTTPS endpoint today. ChatGPT supports remote MCP servers only — to use this server in ChatGPT you'll need to deploy it to a public HTTPS URL first (e.g. via Cloudflare Workers or Vercel) or wait for an official remote build.

```none

```

## At a glance

- **Maintainer:** Community
- **Transport:** stdio
- **Auth model:** API key
- **Required secrets:** TELEGRAM_BOT_TOKEN
- **Supported clients:** Claude, Cursor, VS Code, Any MCP-compatible client, Telegram bot account
- **License:** MIT
- **Language:** TypeScript
- **Latest version:** latest
- **Last verified:** 2026-05-27
- **GitHub stars:** 1,136 (fetched 2026-06-02T11:55:52.388Z)
- **Score:** 79/100 (rubric 2026-04 — see https://top-mcps.com/about/methodology)
- **Source:** https://github.com/chigwell/telegram-mcp

## Security & scope

- **Access scope:** network
- **Sandbox:** Telegram bot token in env. Token grants the full bot identity; rotate via @BotFather if it leaks. The bot can only post in chats it has been added to.
- **Gotchas:**
  - Bot tokens, if leaked, give full bot identity — anyone can post as the bot. Treat like any API key.
  - Telegram rate-limits messages per chat (30/sec) and per bot (no fixed number but enforced).
  - Channel posts cannot be deleted past the configured retention window.

## Quick answer

**What it does.** Connects to a Telegram bot identity and exposes send-message, get-updates, and chat-info tools to AI models.

**Best for:**
- Notification channels
- Lightweight chatbots
- Read-only group summarisation
- Cross-platform alerts

**Not for:**
- Impersonating a real user account
- High-volume marketing (use a marketing-specific platform)

## Description

A community-maintained MCP that wraps the Telegram Bot API so an AI agent can send messages, read updates from chats the bot is in, and respond to commands. Designed for notification flows (send updates to a channel) and lightweight assistant flows (respond to user messages from a chat).

## Why it matters

Telegram is the default messaging app outside the US for a huge chunk of the world. Bots are first-class. An MCP unlocks agent-driven notifications and lightweight assistants on the platform.

## Key features

- Bot-token auth
- Send / edit / delete messages
- Get updates (long-poll or webhook)
- Channel + group + private chat support
- Markdown / HTML message formatting

## FAQ

### Bot or user account?

Bot only. Telegram's API design makes user-account automation a violation of terms; the MCP intentionally only supports bot identities.

### How do I get the bot in a channel?

Create the bot via @BotFather, then add it to the channel/group as an admin. It can only post to chats it has been explicitly invited to.

### Markdown support?

Yes — both MarkdownV2 and HTML parse modes are supported. Choose one and stick with it; the escape rules differ.

### Webhook or polling?

Polling is the default and simplest. For higher-volume bots, set up a webhook endpoint and pass its URL via the configure tool.

## Changelog

- **2026-05-27** — Refreshed install snippets and fact sheet; verified for 2026.
- **2025-03-20** — Initial directory listing.