Summary
Connects Claude to the Telegram Bot API so you can send messages, check bot status, and poll for updates without writing integration code yourself. You get three tools: send_message for pushing text to chats, get_me for bot info, and get_updates for fetching recent activity. Requires a bot token from BotFather and runs over stdio transport. Reach for this when you want Claude to interact with Telegram channels or groups directly, like monitoring conversations, posting notifications, or building automated responses. The resource endpoint exposes bot status for quick health checks.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
Tools
Public tool metadata for what this MCP can expose to an agent.
27 tools
tg_get_meGet basic information about the bot: id, username, first_name, can_join_groups, can_read_all_group_messages, supports_inline_queries.1 params
Get basic information about the bot: id, username, first_name, can_join_groups, can_read_all_group_messages, supports_inline_queries.
Parameters* required
_fieldsstringComma-separated list of fields to include in the response (e.g. "id,username,first_name")
tg_set_my_commandsSet the list of bot commands shown in the Telegram chat menu. Each command has a "command" (1-32 chars, lowercase a-z, 0-9, _) and a "description" (1-256 chars). Max 100 commands.3 params
Set the list of bot commands shown in the Telegram chat menu. Each command has a "command" (1-32 chars, lowercase a-z, 0-9, _) and a "description" (1-256 chars). Max 100 commands.
Parameters* required
scopeobjectOptional scope e.g. {"type":"all_private_chats"}
commandsarrayArray of BotCommand objects
language_codestringTwo-letter ISO 639-1 language code
tg_send_messageSend a text message to a chat. Supports Markdown, MarkdownV2, and HTML formatting. Can include inline keyboards via reply_markup.7 params
Send a text message to a chat. Supports Markdown, MarkdownV2, and HTML formatting. Can include inline keyboards via reply_markup.
Parameters* required
textstringMessage text (1-4096 characters)
chat_idstringChat ID (number) or @channel_username
parse_modestring"Markdown", "MarkdownV2", or "HTML"
reply_markupobjectInlineKeyboardMarkup, ReplyKeyboardMarkup, etc.
protect_contentbooleanPrevent message from being forwarded/saved
reply_to_message_idnumberMessage ID to reply to
disable_notificationbooleanSend silently (no notification sound)
tg_send_photoSend a photo to a chat. Provide a URL or file_id from a previously uploaded photo.6 params
Send a photo to a chat. Provide a URL or file_id from a previously uploaded photo.
Parameters* required
photostringPhoto URL or file_id
captionstringPhoto caption (0-1024 characters)
chat_idstringChat ID or @channel_username
parse_modestringCaption parse mode
reply_markupobjectOptional reply markup
reply_to_message_idnumberMessage ID to reply to
tg_send_documentSend a document/file to a chat. Provide a URL or file_id. Max 50MB for bots.5 params
Send a document/file to a chat. Provide a URL or file_id. Max 50MB for bots.
Parameters* required
captionstringDocument caption (0-1024 characters)
chat_idstringChat ID or @channel_username
documentstringDocument URL or file_id
parse_modestringCaption parse mode
reply_markupobjectOptional reply markup
tg_send_videoSend a video to a chat. Provide a URL or file_id. Supports MPEG4 format, max 50MB.7 params
Send a video to a chat. Provide a URL or file_id. Supports MPEG4 format, max 50MB.
Parameters* required
videostringVideo URL or file_id
widthnumberVideo width
heightnumberVideo height
captionstringVideo caption
chat_idstringChat ID or @channel_username
durationnumberDuration in seconds
parse_modestringCaption parse mode
tg_send_audioSend an audio file to a chat. Displayed as a music player. Provide a URL or file_id. Max 50MB, MP3/M4A format.7 params
Send an audio file to a chat. Displayed as a music player. Provide a URL or file_id. Max 50MB, MP3/M4A format.
Parameters* required
audiostringAudio URL or file_id
titlestringTrack name
captionstringAudio caption
chat_idstringChat ID or @channel_username
durationnumberDuration in seconds
performerstringPerformer name
parse_modestringCaption parse mode
tg_send_locationSend a geographic location point to a chat.4 params
Send a geographic location point to a chat.
Parameters* required
chat_idstringChat ID or @channel_username
latitudenumberLatitude (-90 to 90)
longitudenumberLongitude (-180 to 180)
reply_markupobjectOptional reply markup
tg_send_pollSend a poll to a chat. Supports regular polls and quiz mode. For quiz mode, set type to "quiz" and provide correct_option_id.7 params
Send a poll to a chat. Supports regular polls and quiz mode. For quiz mode, set type to "quiz" and provide correct_option_id.
Parameters* required
typestring"regular" or "quiz"
chat_idstringChat ID or @channel_username
optionsarrayAnswer options (2-10 strings, each 1-100 chars)
questionstringPoll question (1-300 characters)
is_anonymousbooleanAnonymous poll (default: true)
correct_option_idnumberRequired for quiz: 0-based index of correct answer
allows_multiple_answersbooleanAllow multiple answers (regular polls only)
tg_send_contactSend a phone contact card to a chat.4 params
Send a phone contact card to a chat.
Parameters* required
chat_idstringChat ID or @channel_username
last_namestringContact last name
first_namestringContact first name
phone_numberstringContact phone number
tg_edit_message_textEdit the text of a previously sent message. The bot must be the author of the message.5 params
Edit the text of a previously sent message. The bot must be the author of the message.
Parameters* required
textstringNew text (1-4096 characters)
chat_idstringChat ID
message_idnumberMessage ID to edit
parse_modestringParse mode for new text
reply_markupobjectNew inline keyboard markup
tg_edit_message_captionEdit the caption of a previously sent media message (photo, video, document, audio).5 params
Edit the caption of a previously sent media message (photo, video, document, audio).
Parameters* required
captionstringNew caption (0-1024 characters)
chat_idstringChat ID
message_idnumberMessage ID to edit
parse_modestringParse mode for caption
reply_markupobjectNew inline keyboard markup
tg_delete_messageDelete a message. Bot must have delete permission in group chats. Messages older than 48 hours cannot be deleted.2 params
Delete a message. Bot must have delete permission in group chats. Messages older than 48 hours cannot be deleted.
Parameters* required
chat_idstringChat ID
message_idnumberMessage ID to delete
tg_get_chatGet detailed information about a chat: title, description, type, member count, permissions, pinned message, etc.1 params
Get detailed information about a chat: title, description, type, member count, permissions, pinned message, etc.
Parameters* required
chat_idstringChat ID or @channel_username
tg_get_chat_member_countGet the number of members in a chat.1 params
Get the number of members in a chat.
Parameters* required
chat_idstringChat ID or @channel_username
tg_get_chat_memberGet information about a specific member: status (creator, administrator, member, restricted, left, kicked), permissions, and custom title.2 params
Get information about a specific member: status (creator, administrator, member, restricted, left, kicked), permissions, and custom title.
Parameters* required
chat_idstringChat ID or @channel_username
user_idnumberTelegram user ID
tg_ban_chat_memberBan a user from a group, supergroup, or channel. The user will be unable to return unless unbanned. Bot must be admin with ban permission.4 params
Ban a user from a group, supergroup, or channel. The user will be unable to return unless unbanned. Bot must be admin with ban permission.
Parameters* required
chat_idstringChat ID
user_idnumberUser ID to ban
until_datenumberUnix timestamp for ban expiry (0 or omit for permanent)
revoke_messagesbooleanDelete all messages from this user in the chat
tg_unban_chat_memberUnban a previously banned user. The user is NOT added back automatically and must rejoin via invite link.3 params
Unban a previously banned user. The user is NOT added back automatically and must rejoin via invite link.
Parameters* required
chat_idstringChat ID
user_idnumberUser ID to unban
only_if_bannedbooleanOnly unban if currently banned (default: false)
tg_set_webhookSet a webhook URL for receiving Telegram updates. Telegram sends POST requests with JSON Update objects to this URL. Supported ports: 443, 80, 88, 8443.4 params
Set a webhook URL for receiving Telegram updates. Telegram sends POST requests with JSON Update objects to this URL. Supported ports: 443, 80, 88, 8443.
Parameters* required
urlstringHTTPS URL for receiving updates
secret_tokenstringSecret token for X-Telegram-Bot-Api-Secret-Token header (1-256 chars)
allowed_updatesarrayUpdate types to receive, e.g. ["message","callback_query"]
max_connectionsnumberMax simultaneous connections (1-100, default 40)
tg_delete_webhookRemove the webhook integration. After this, you can use getUpdates for polling.1 params
Remove the webhook integration. After this, you can use getUpdates for polling.
Parameters* required
drop_pending_updatesbooleanDrop all pending updates
tg_get_webhook_infoGet current webhook status: URL, pending update count, last error date/message, max connections, and allowed update types.1 params
Get current webhook status: URL, pending update count, last error date/message, max connections, and allowed update types.
Parameters* required
_fieldsstringComma-separated list of fields to include in the response (e.g. "url,pending_update_count")
tg_answer_callback_queryAnswer a callback query from an inline keyboard button press. Must be called to stop the loading indicator on the button.3 params
Answer a callback query from an inline keyboard button press. Must be called to stop the loading indicator on the button.
Parameters* required
textstringNotification text (0-200 chars)
show_alertbooleanShow as alert popup instead of notification at top
callback_query_idstringCallback query ID from the update
tg_get_fileGet file info and download URL. Returns file_id, file_size, file_path, and a ready-to-use download_url. Files up to 20MB.1 params
Get file info and download URL. Returns file_id, file_size, file_path, and a ready-to-use download_url. Files up to 20MB.
Parameters* required
file_idstringFile identifier from a message
tg_get_user_profile_photosGet a list of profile photos for a user.3 params
Get a list of profile photos for a user.
Parameters* required
limitnumberMax photos to return (1-100, default 100)
offsetnumberPhoto offset for pagination
user_idnumberTelegram user ID
tg_pin_chat_messagePin a message in a chat. Bot must have pin_messages admin permission in groups/supergroups.3 params
Pin a message in a chat. Bot must have pin_messages admin permission in groups/supergroups.
Parameters* required
chat_idstringChat ID
message_idnumberMessage ID to pin
disable_notificationbooleanPin silently (no notification)
tg_unpin_chat_messageUnpin a message in a chat. If message_id is not provided, unpins the most recent pinned message.2 params
Unpin a message in a chat. If message_id is not provided, unpins the most recent pinned message.
Parameters* required
chat_idstringChat ID
message_idnumberMessage ID to unpin (omit to unpin latest)
tg_create_chat_invite_linkCreate an additional invite link for a chat. Bot must be admin with invite_users permission.4 params
Create an additional invite link for a chat. Bot must be admin with invite_users permission.
Parameters* required
namestringInvite link name (0-32 chars)
chat_idstringChat ID
expire_datenumberUnix timestamp when the link expires
member_limitnumberMax users that can join via this link (1-99999)
mcp-telegram-bot
MCP server that exposes a Telegram bot
Install
pip install mcp-telegram-bot
Setup
- Create a Telegram bot by talking to @BotFather on Telegram
- Get your bot token
- Set the
TELEGRAM_BOT_TOKENenvironment variable
Usage
export TELELEGRAM_BOT_TOKEN="your-bot-token-here"
mcp-telegram-bot
MCP Tools
- send_message: Send a message to a Telegram chat
- get_me: Get bot information
- get_updates: Get recent updates from Telegram
MCP Resources
- bot://status: Get bot status
mcp-name: io.github.daedalus/mcp-telegram-bot
Development
git clone https://github.com/daedalus/mcp-telegram-bot.git
cd mcp-telegram-bot
pip install -e ".[test]"
# run tests
pytest
# format
ruff format src/ tests/
# lint
ruff check src/ tests/
# type check
mypy src/
License
MIT
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →Categories
Registryactive
Packagemcp-telegram-bot
TransportSTDIO
UpdatedMar 28, 2026
