MCP Telegram
@tacticlaunch
About MCP Telegram
Telegram MCP server (MTProto). Connect Claude, Cursor, Claude Code, VS Code, Codex, Cline, Windsurf to a real Telegram account — read/search/send messages, moderate channels, manage stories/contacts/folders, transcribe voice, and call any raw MTProto method. Browser-based sign-in
Basic information
Config
Add this server to your MCP-compatible client using the configuration below.
{
"mcpServers": {
"mcp-telegram-tacticlaunch": {
"command": "npx",
"args": [
"mcp-telegram",
"sign-in"
]
}
}
}Tools
50Open the browser-based sign-in flow. Adds an account.
List signed-in accounts.
List dialogs/chats/channels. Filters: `unread`, `archived`, `ignorePinned`, `folder`, `limit`.
List messages in a dialog. Newest first.
Search inside one dialog: `query`, `filter` (photos/videos/url/voice/...), `fromUser`, date range.
Search across every chat you have.
Find dialogs by name/title/username substring.
Send text. Supports `replyTo`, `topMsgId`, `parseMode`, `schedule`, `silent`.
Send a file (local path or `https://` URL). Pass an array for an album.
Save the media on a message to disk.
Transcribe a voice/video note (Premium).
Call any raw MTProto method by name. Auto-resolves `peer`/`channel`/`user` strings.
List signed-in accounts.
Browser-based sign-in. Adds an account.
Drop a local session and revoke it on Telegram.
Open the local settings page (tool surface + read-only).
Return the profile of the authenticated user.
Change own first/last name and bio.
Set or clear own `@username`.
Set the account birthday.
Upload a new avatar (local path or URL).
List dialogs. Filters: `unread`, `archived`, `ignorePinned`, `folder`, `limit`.
Find dialogs by name/title/username substring.
Resolve `@username` to a user/channel/chat entity.
List custom dialog folders (chat filters).
List contacts.
List messages in a dialog.
Search inside one dialog (text, type filter, sender, date range).
Search across every chat.
Fetch one or more messages by id.
Get reactions on messages.
Mark messages read up to an id.
Send text.
Edit a previously sent message.
Delete by id (optionally revoke for all).
Forward messages between dialogs.
Set reactions on a message.
Send to a phone number, auto-creates a temporary contact.
Send a file (path or URL). Albums via array.
Save a message's media to disk.
Save a peer's avatar to disk.
Transcribe voice/video (Premium).
Send a poll. Supports quiz, multiple-choice, anonymous, close period.
Cast a vote.
Finalize a poll.
Fetch tally.
Set emoji reactions on a message.
Read reactions.
Set account-wide default.
Feed of contacts' stories.
Overview
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.
More Communication MCP servers
Email sending MCP 💌
resendThe official MCP server to send emails and interact with Resend
Slack MCP Server
korotovskyThe most powerful MCP Slack Server with no permission requirements, Apps support, GovSlack, DMs, Group DMs and smart history fetch logic.
MCP Teams Server
InditexTechAn MCP (Model Context Protocol) server implementation for Microsoft Teams integration, providing capabilities to read messages, create messages, reply to messages, mention members.
Telegram MCP Server
kfastovTelegram user console client and archiver
mcp-email-server
ai-zerolabIMAP and SMTP via MCP Server
Comments