MCP Telegram

What is MCP Telegram?

MCP Telegram is a Model Context Protocol (MCP) server that connects any MCP‑compatible client (Claude Desktop, Codex CLI, Cursor, VS Code, Claude Code, Cline, Windsurf, Goose, and others) to a real Telegram user account via MTProto. It lets an agent read, search, send, moderate, and manage Telegram chats through tool calls instead of using the Telegram UI. No bot is required; it signs in as a real Telegram user.

How to use MCP Telegram?

Install the server automatically with npx add-mcp mcp-telegram (which configures the client for you) or manually by adding the command and environment variables to your MCP client’s config. You must set the TELEGRAM_API_ID and TELEGRAM_API_HASH environment variables, obtained from my.telegram.org/apps. On first use, ask your agent to call the login tool, which opens a browser‑based sign‑in flow. Node.js version 20 or later is required.

Key features of MCP Telegram

• 102 tools covering the full Telegram user‑account surface
• Signs in as a real Telegram user (not a bot)
• Browser‑based local sign‑in flow
• Session data stored in ~/.telegram-agent/
• Supports multiple signed‑in accounts
• Raw MTProto bridge (invoke_mtproto) for custom calls
• Works with many MCP clients (Claude, Codex, Cursor, etc.)

Use cases of MCP Telegram

• Read dialogs and search messages globally across all chats
• Send, edit, forward, react to, and delete messages
• Download media and transcribe voice/video notes
• Moderate channels: ban/restrict users, promote admins, manage invite links and slow‑mode
• Manage stories, contacts, drafts, notification settings, folders, and privacy

FAQ from MCP Telegram

What are the prerequisites for using MCP Telegram?

Node.js version 20 or later and Telegram API credentials (api_id and api_hash) from my.telegram.org/apps. Both environment variables are required.

Where are Telegram sessions stored?

Session data is saved in the ~/.telegram-agent/ directory on your local machine. The README warns to treat that directory like a password.

Can I use a bot instead of a user account?

No. MCP Telegram signs in as a real Telegram user account via MTProto. It does not use a bot token.

What is the difference between mcp-telegram and the telegram‑agent companion?

mcp-telegram is a full MCP server that exposes all tool schemas (~12,700 tokens) in the agent’s context on every turn. The companion telegram-agent package provides the same Telegram surface as a skill that loads only when the agent mentions Telegram, offering ~50× lower context cost when idle. They share the same ~/.telegram-agent/ session store.

How do I sign in for the first time?

Ask your agent to call the login tool. A browser tab opens; enter your phone number, the SMS code, and your 2FA password if you have one. After a green checkmark appears, close the tab. The session is stored locally.