Telegram MCP server

Last verified: 2026-09

Send and read Telegram via a bot.

Community Chat, mail & docs Needs a secret Claude Desktop, Cursor, Windsurf, Claude Code

What it does

User-account Telegram MCP (login flow, then send/edit/delete, search dialogs, drafts, media download). This is not a bot-only wrapper — treat it as your user session.

It sits in Chat, mail & docs: These servers act as the bot or the integration you install.

Good for

Read saved messages after you have completed the login flow.
Send a message to a test group, not a customer channel.
Search dialogs for a link you know you saved.
Download media only from chats you trust.

Tools

send_message / edit_message / delete_message — Outbound.
get_messages / search_dialogs / message_from_link — Inbound and search.
get_draft / set_draft / media_download — Drafts and files.

Config (Claude Desktop / Cursor / Windsurf)

Paste the JSON below. Same mcpServers shape. Replace placeholder paths and secrets. Windows paths look like C:\\Users\\you\\project, not /path/to. Host-side steps →

Claude Desktop

OS	Config file
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json` (usually `C:\Users\<you>\AppData\Roaming\Claude\`)
Linux	`~/.config/Claude/claude_desktop_config.json`

Cursor

Scope	macOS / Linux	Windows
This project	`.cursor/mcp.json` in the repo root
This user	`~/.cursor/mcp.json`	`%USERPROFILE%\.cursor\mcp.json`

Windsurf

OS	Config file
macOS / Linux	`~/.codeium/windsurf/mcp_config.json`
Windows	`%USERPROFILE%\.codeium\windsurf\mcp_config.json`

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": [
        "-y",
        "telegram-mcp"
      ],
      "env": {
        "TELEGRAM_API_ID": "...",
        "TELEGRAM_API_HASH": "...",
        "TELEGRAM_BOT_TOKEN": "only if the package is in bot mode"
      }
    }
  }
}

Windsurf remote MCP: use serverUrl instead of url if the block below is HTTP.

One-liner: npx -y telegram-mcp

Secrets it wants: TELEGRAM_BOT_TOKEN

Source repo →

How to get started

Create a Telegram API id/hash, run the login flow the README describes.
Confirm you are talking to a user session, not a bot, before you leave it running.
Start with get_messages on a saved-messages chat.

Access risk

A user session is the whole Telegram account, including private chats.

When to skip it

Skip it if a bot token + one channel is enough (then look for a bot-only server). Skip it on a shared machine.

Instead: Discord, Slack, Gmail.

Chat, mail & docsDiscordRead and send Discord messages. OfficialSlackRead channels and post messages. Chat, mail & docsGmailRead and draft Gmail.

Vs alternatives

Server	Official?	Needs a secret?	Best for
Telegram	No	Yes	Send and read Telegram via a bot.
Discord	No	Yes	Read and send Discord messages.
Slack	Yes	Yes	Read channels and post messages.
Gmail	No	Yes	Read and draft Gmail.

More in Chat, mail & docs

OfficialGoogle MapsGeocode and place search via Google Maps. OfficialSlackRead channels and post messages. Chat, mail & docsAsanaTasks and projects in Asana. Chat, mail & docsConfluenceRead Confluence pages.

All 18 in this category →

FAQ

Bot token or user session?

This package's login flow is a user session (API id/hash). That is the whole Telegram account, including private chats. Do not run it on a shared machine.

TELEGRAM_BOT_TOKEN in our listing?

Only if you put the package in bot mode. Read the README. Default risk is user-session.

Telegram or Discord?

Discord bot in one guild is smaller than a Telegram user session.

Can it delete messages?

delete_message is in the tool list. Yes.