beautyfree/mcp-telegram

mcp-telegram

Telegram MCP server for Claude, Codex, Cursor, Claude Code, VS Code, Cline, Windsurf, and other MCP clients. Real Telegram user account via MTProto, browser-based local sign-in, 100+ tools. Need lazy-loading + lower context cost? See telegram-agent, the skill-based companion.

A Model Context Protocol (MCP) server that connects Claude Desktop, Codex CLI, Cursor, Claude Code, VS Code, Cline, Windsurf, Goose, and any other MCP-compatible client to a real Telegram user account via MTProto—so your agent can read, search, send, moderate, and manage Telegram chats from chat or automated tool calls instead of clicking through the Telegram UI.

Use it to: read dialogs and search messages globally · send/edit/forward/react/poll · download media and transcribe voice notes · moderate channels (ban/restrict/promote, invite links, slow-mode, admin log, forum topics) · manage stories, contacts, drafts, notifications, folders, privacy · or fall through to the raw MTProto bridge for anything else. All against a single signed-in user account—no bot required.

[!WARNING] This server signs in as a real Telegram user (not a bot). Sessions live in ~/.telegram-agent/. Treat that directory like a password.

Prerequisites

1. Node.js >=20
2. Telegram API credentials from my.telegram.org/apps — api_id and api_hash

Want a lighter transport?

This package is the MCP server — every tool schema (~12,700 tokens) sits in your agent’s context on every turn. Good for any MCP client and for hosted runtimes that can’t shell out.

If your agent is Claude Code / Codex CLI / Cursor / Gemini CLI / Cline / Windsurf, there’s a companion package — telegram-agent — that ships the same Telegram surface as a universal agent skill. The agent only loads the skill instructions when your prompt mentions Telegram — ~50× lower context cost in idle. Standalone (no MCP server in the loop), but uses the same ~/.telegram-agent/ session store as this package — sign in once, use either or both.

npm i -g telegram-agent
telegram-agent login
npx skills add beautyfree/telegram-agent -a claude-code -g

Continue below for the MCP install path.

Install

Option A — automatic, all clients:

npx add-mcp mcp-telegram \
  --env TELEGRAM_API_ID=123456 \
  --env TELEGRAM_API_HASH=abc...

add-mcp (from Neon) writes the correct config for Claude Desktop, Claude Code, Cursor, VS Code, Codex, Gemini CLI, Cline, Zed, Goose, OpenCode, and others. Pick the client in the interactive prompt.

[!IMPORTANT] Both env vars are required. Get them from my.telegram.org/apps.

Option B — manual config:

First-time sign in

Ask your agent:

Sign in to my Telegram.

The agent calls the login tool. A browser tab opens. Enter your phone number, the SMS code, and 2FA password if you have one. The tab shows a green checkmark — you can close it. The session is now stored locally and the agent can read your Telegram.

To add another account, ask the agent to call login again.

Tools

102 tools covering the full Telegram user-account surface. Common ones below; the rest are grouped under collapsibles. Every tool accepts an optional accountId (omit when only one account is signed in). peer accepts a numeric chat id, an @username, or the literal "me" (Saved Messages).

Top of the menu:

Gating which tools are exposed

Three env vars, applied in order:

Examples:

MCP_TELEGRAM_READONLY=1                                    # read-only agent
MCP_TELEGRAM_TOOLS='login,list*,search*,get*'              # discovery-only
MCP_TELEGRAM_DISABLE='delete*,ban*,kick*,create_channel,delete_channel,transfer_ownership,invokeMtproto'  # safer write set

Environment

Choosing which tools the agent sees

The three gating vars stack — MCP_TELEGRAM_READONLY → MCP_TELEGRAM_TOOLS → MCP_TELEGRAM_DISABLE.

# Read-only agent — every mutating tool is hidden
MCP_TELEGRAM_READONLY=1

# Discovery-only — only login + the list/search/get tools
MCP_TELEGRAM_TOOLS='login,list*,search*,get*,resolveUsername'

# Allow writes but keep destructive ones away from the agent
MCP_TELEGRAM_DISABLE='delete*,ban*,kick*,create_channel,delete_channel,transfer_ownership,invokeMtproto'

# Specific surface: read + send/edit only
MCP_TELEGRAM_TOOLS='login,list_accounts,list_dialogs,list_messages,search_messages,search_global,send_message,editMessage'

In an MCP client config, drop these into the same env block as TELEGRAM_API_ID/TELEGRAM_API_HASH. To verify, re-open your client — the tools the server advertises are exactly the ones registered after the gates run.

Data layout

~/.telegram-agent/
├── state.json          known accounts (no secrets in here)
└── sessions/
    └── /   per-account MTProto session

If a Telegram session is invalidated server-side (logged out from another device, password rotated, etc.), the next tool call returns an error telling the agent to call login to re-authorize.

Development

git clone https://github.com/beautyfree/mcp-telegram
cd mcp-telegram
npm install
echo "TELEGRAM_API_ID=...\nTELEGRAM_API_HASH=..." > .env
npm run dev

Layout:

src/
├── index.ts           bin entry — stdio MCP server, tool registrations
├── telegram.ts        MTProto client + login state machine
├── auth-browser.ts    ephemeral HTTP server that drives the browser flow
├── auth-page.ts       inline HTML for the auth page
├── state.ts           persistent state in ~/.telegram-agent/
└── logger.ts

License

MIT — see LICENSE.

---