Telegram MCP server
Bridge AI assistants to your Telegram account: read dialogs, summarize unread messages, mark as read, and send drafts.
Add to your client
Copy the config for your MCP client and paste it into its config file.
npx -y @chaindead/telegram-mcpPaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"telegram-mcp-server": {
"command": "telegram-mcp",
"args": [],
"env": {
"TG_APP_ID": "<your-app-id>",
"TG_API_HASH": "<your-api-hash>",
"PATH": "<path_to_telegram-mcp_binary_dir>",
"HOME": "<path_to_your_home_directory"
}
}
}
}Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- A Telegram account
- Telegram API ID and API hash from https://my.telegram.org/auth
- One-time CLI authorization: telegram-mcp auth --app-id <id> --api-hash <hash> --phone <phone> (add --password for 2FA)
- Install via Homebrew, release binary, or go install (Go 1.24+); alternatively run via npx (macOS, Linux, Windows)
About Telegram MCP server
An MCP server that bridges the Telegram API (via MTProto) to AI assistants like Claude Desktop and Cursor. It lets an assistant read account info, list dialogs with an optional unread filter, fetch messages from a specific dialog, mark dialogs as read, and send draft messages. Distributed as a Go binary (Homebrew, release archives, or go install) or runnable via npx, it runs locally over stdio after a one-time CLI authorization with a Telegram API ID and hash.
Tools & capabilities (5)
tg_meGet current account information.
tg_dialogsList dialogs with an optional unread filter.
tg_readMark a dialog as read.
tg_dialogRetrieve messages from a specific dialog.
tg_sendSend draft messages to any dialog.
When to use it
- Check for and summarize unread Telegram messages
- Read and analyze unread messages and prepare draft responses
- Analyze dialogs and suggest a folder structure or categorize chats by importance
- Monitor a specific chat for updates about a topic
- Draft a polite response to the last message in a chat
- Find unanswered questions across your chats
Security notes
Connects to your personal Telegram account via MTProto. Requires a Telegram API ID and hash from https://my.telegram.org/auth and a one-time CLI authorization (telegram-mcp auth --app-id <id> --api-hash <hash> --phone <phone>); add --password for 2FA. Review the Telegram API Terms of Service first, as misuse may result in account suspension. Credentials (TG_APP_ID, TG_API_HASH) are passed as environment variables.
Telegram MCP server FAQ
How do I authorize the server?
Get an API ID and hash from https://my.telegram.org/auth, then run: telegram-mcp auth --app-id <your-api-id> --api-hash <your-api-hash> --phone <your-phone-number>, and enter the code Telegram sends you. If you have 2FA enabled, add --password <2fa_password>; to override an existing session, add --new.
Can I run it without installing a binary?
Yes. You can run the latest version directly with npx on macOS, Linux, and Windows: npx -y @chaindead/telegram-mcp. Auth and client config use the npx command form (e.g. command "npx" with args ["-y", "@chaindead/telegram-mcp"]).
My MCP client rejects the server's tools (e.g. VS Code). What can I do?
Some clients do not support JSON Schema Draft 2020-12 (the default). Override the schema version with the --schema-version flag or the TG_SCHEMA_VERSION environment variable; Draft-07 (https://json-schema.org/draft-07/schema#) is recommended for VS Code.
Alternatives to Telegram MCP server
Compare all alternatives →
Connect your personal WhatsApp: search, read and send messages and media locally
Powerful Slack MCP with stdio/SSE/HTTP, DMs, group DMs and no-admin token auth
Full Telegram user-account MCP via MTProto: read chats, manage groups, send messages
Compare Telegram MCP server with: