Yes. telegram-mcp is free and open source under the Apache 2.0 license. You only need free Telegram API credentials from my.telegram.org; there is no separate fee for the server.

Does it support remote/OAuth?

No. It runs locally over stdio and authenticates with a Telethon session string derived from your Telegram API ID and hash, not OAuth. There is no hosted remote endpoint.

Does it use a bot or my real account?

It drives your real Telegram user account through MTProto (Telethon), so it can do anything you can in the app. Treat the write tools carefully and consider TELEGRAM_EXPOSED_TOOLS to limit what is enabled.

Telegram MCP server

Communitychigwell (Eugene Evstafev)1,200Config last verified Jun 1, 2026

A maintained Telegram MCP server powered by Telethon: read chats, manage groups and contacts, and send or modify messages, media, and more from your agent.

telegram-mcp is a comprehensive, actively maintained Telegram MCP server that drives a real Telegram user account through the Telethon MTProto library, giving an agent the same reach a person has in the app. It exposes a very broad surface — well over a hundred tools — spanning chats and groups (list, inspect, create groups and channels, join or leave, invite users, manage admins and bans, set permissions, slow mode, topics, and invite links), messages (send, schedule, edit, delete, forward, pin, mark read, reply, search, polls, reactions, and inline-button presses), contacts (list, search, add, delete, block, import, and export), media (send files, voice notes, stickers, GIFs, and download media), profile and privacy settings, and Telegram folders and drafts. Multiple accounts can be configured and addressed by label.

It runs locally over stdio. You authenticate by generating a Telethon session string from your Telegram API credentials (TELEGRAM_API_ID and TELEGRAM_API_HASH from my.telegram.org), then run the server with that TELEGRAM_SESSION_STRING. An optional TELEGRAM_EXPOSED_TOOLS variable prunes the tool set. The project is open source under the Apache 2.0 license. Because it acts as your full user account, scope and approve write tools carefully.

Quick install

Copy-paste configs are provided for all 8 supported clients. Pick your client below.

Add to ~/.claude.json

~/.claude.json

json

{
  "mcpServers": {
    "telegram": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/chigwell/telegram-mcp",
        "telegram-mcp"
      ],
      "env": {
        "TELEGRAM_API_ID": "<TELEGRAM_API_ID>",
        "TELEGRAM_API_HASH": "<TELEGRAM_API_HASH>",
        "TELEGRAM_SESSION_STRING": "<TELEGRAM_SESSION_STRING>",
        "TELEGRAM_EXPOSED_TOOLS": "<TELEGRAM_EXPOSED_TOOLS>"
      }
    }
  }
}

Or via CLI

bash

claude mcp add telegram -- uvx --from git+https://github.com/chigwell/telegram-mcp telegram-mcp

Step-by-step guides

Available tools

Tool	Description
list_accounts	Lists all configured Telegram accounts with profile info.
get_chats	Gets a paginated list of your chats.
subscribe_public_channel	Subscribes (joins) a public channel.
list_topics	Lists forum topics in a chat.
list_chats	Lists chats with optional filtering.
get_chat	Gets details of a chat by ID or username.
search_public_chats	Searches public chats by query.
resolve_username	Resolves a username to its entity ID.
get_full_chat	Gets full metadata for a chat.
mute_chat	Mutes notifications for a chat.
unmute_chat	Unmutes notifications for a chat.
archive_chat	Archives a chat.
unarchive_chat	Unarchives a chat.
get_common_chats	Gets chats you have in common with a user.
get_message_read_by	Gets which users have read a message.
get_message_link	Gets a shareable link to a message.
list_contacts	Lists your Telegram contacts.
search_contacts	Searches your contacts by query.
get_contact_ids	Gets the IDs of your contacts.
get_direct_chat_by_contact	Finds the direct chat with a contact.
get_contact_chats	Gets chats associated with a contact.
get_last_interaction	Gets your last interaction with a contact.
add_contact	Adds a new contact.
delete_contact	Deletes a contact.
block_user	Blocks a user.
unblock_user	Unblocks a user.
import_contacts	Imports a batch of contacts.
export_contacts	Exports your contacts.
get_blocked_users	Lists users you have blocked.
send_contact	Sends a contact card to a chat.
wait_for_new_message	Waits for the next new incoming message.
wait_for_settled_message	Waits until incoming messages settle, then returns them.
list_folders	Lists your Telegram folders.
get_folder	Gets a folder by ID.
create_folder	Creates a new folder.
add_chat_to_folder	Adds a chat to a folder.
remove_chat_from_folder	Removes a chat from a folder.
delete_folder	Deletes a folder.
reorder_folders	Reorders your folders.
create_group	Creates a new group with the given users.
invite_to_group	Invites users to a group.
leave_chat	Leaves a chat or group.
get_participants	Lists participants of a chat.
create_channel	Creates a new channel.
edit_chat_title	Edits a chat's title.
edit_chat_photo	Edits a chat's photo.
edit_chat_about	Edits a chat's description.
delete_chat_photo	Deletes a chat's photo.
promote_admin	Promotes a user to admin.
demote_admin	Demotes an admin.
ban_user	Bans a user from a chat.
unban_user	Unbans a user from a chat.
set_default_chat_permissions	Sets default permissions for a chat.
toggle_slow_mode	Toggles slow mode for a chat.
edit_admin_rights	Edits an admin's rights.
get_admins	Lists admins of a chat.
get_banned_users	Lists banned users of a chat.
get_invite_link	Gets a chat's invite link.
join_chat_by_link	Joins a chat by invite link.
export_chat_invite	Exports a chat invite link.
import_chat_invite	Joins a chat using an invite hash.
get_recent_actions	Gets the recent admin actions log for a chat.
send_file	Sends a file to a chat.
send_album	Sends an album of media to a chat.
download_media	Downloads media from a message.
send_voice	Sends a voice note to a chat.
upload_file	Uploads a file to Telegram.
get_media_info	Gets info about a message's media.
get_sticker_sets	Lists available sticker sets.
send_sticker	Sends a sticker to a chat.
get_gif_search	Searches for GIFs.
send_gif	Sends a GIF to a chat.
get_messages	Gets messages from a chat.
send_message	Sends a text message to a chat.
send_scheduled_message	Schedules a message to send later.
get_scheduled_messages	Lists scheduled messages in a chat.
delete_scheduled_message	Deletes a scheduled message.
list_inline_buttons	Lists inline buttons on a message.
press_inline_button	Presses an inline callback button on a message.
list_messages	Lists messages in a chat with filtering.
get_message_context	Gets surrounding context for a message.
forward_message	Forwards a message to another chat.
forward_messages	Forwards multiple messages to another chat.
edit_message	Edits a message you sent.
delete_message	Deletes a message.
delete_chat_history	Deletes the history of a chat.
delete_messages_bulk	Deletes multiple messages at once.
pin_message	Pins a message in a chat.
unpin_message	Unpins a message in a chat.
unpin_all_messages	Unpins all messages in a chat.
mark_as_read	Marks a chat's messages as read.
reply_to_message	Replies to a specific message.
search_messages	Searches messages within a chat.
search_global	Searches messages globally across chats.
get_history	Gets the message history of a chat.
get_pinned_messages	Lists pinned messages in a chat.
create_poll	Creates a poll in a chat.
send_reaction	Adds a reaction to a message.
remove_reaction	Removes a reaction from a message.
get_message_reactions	Gets reactions on a message.
save_draft	Saves a draft message for a chat.
get_drafts	Lists your saved drafts.
clear_draft	Clears the draft for a chat.
get_me	Gets your own account info.
update_profile	Updates your profile fields.
set_profile_photo	Sets your profile photo.
delete_profile_photo	Deletes your profile photo.
get_privacy_settings	Gets your privacy settings.
set_privacy_settings	Updates your privacy settings.
get_full_user	Gets full info about a user.
get_bot_info	Gets info about a bot.
set_bot_commands	Sets command list for a bot you own.
get_user_photos	Gets a user's profile photos.
get_user_status	Gets a user's online status.

Required configuration

TELEGRAM_API_IDRequired
Your Telegram API ID from my.telegram.org.
TELEGRAM_API_HASHRequired
Your Telegram API hash from my.telegram.org.
TELEGRAM_SESSION_STRINGRequired
Telethon session string authorizing your Telegram user account.
TELEGRAM_EXPOSED_TOOLSOptional
Optional comma-separated allowlist that prunes which tools the server exposes.

What you can do with it

Triage and reply to chats from your agent

The agent lists recent chats, reads the latest messages for context, and drafts or sends a reply — useful for staying on top of DMs and group threads without opening the app.

Administer a community group or channel

Manage members and moderation at scale: promote or demote admins, ban or unban users, set permissions and slow mode, manage invite links, and review the recent admin action log.

FAQ

Is it free?: Yes. telegram-mcp is free and open source under the Apache 2.0 license. You only need free Telegram API credentials from my.telegram.org; there is no separate fee for the server.
Does it support remote/OAuth?: No. It runs locally over stdio and authenticates with a Telethon session string derived from your Telegram API ID and hash, not OAuth. There is no hosted remote endpoint.
Does it use a bot or my real account?: It drives your real Telegram user account through MTProto (Telethon), so it can do anything you can in the app. Treat the write tools carefully and consider TELEGRAM_EXPOSED_TOOLS to limit what is enabled.

← Browse all communication servers