Telegram MCP connector

What agents can do

The server has 24 actions (9 read, 15 write). Every action is locked to the chat you connected.

• Bot details: get_me, get_my_name, get_my_description, get_my_short_description and get_my_commands.
• Chat and members: get_chat reads the connected chat's details, and get_chat_member reads a member's status in it.
• Files and photos: get_file and get_user_profile_photos.
• Send: send_message, send_photo, send_video, send_audio, send_location, send_contact and send_poll. Media is sent by link with an optional caption.
• Forward and copy: forward_message and copy_message within the chat.
• Edit and pin: edit_message_text, edit_message_caption, pin_chat_message, unpin_chat_message and unpin_all_chat_messages.
• Delete: delete_message.

Before you connect

• A Telegram account, and a bot created with @BotFather.
• A channel or group where you can add the bot as an administrator that can post messages.
• The Telegram desktop or phone app. The web version doesn't always accept the chat picker.
• An InsightfulPipe workspace with a brand for the chat. Owners, admins and operators can add connections.

Connect Telegram

1. In the InsightfulPipe app, open Connectors, choose Telegram and click Connect.
2. In Telegram, open @BotFather, send /newbot and follow the prompts, then copy the bot token it sends you.
3. Under Permissions, choose Read Only or Read + Write.
4. Paste the token into Bot Token and click Verify Bot.
5. Add the bot to your channel or group as an administrator that can post messages, for example with Add bot to a chat.
6. After adding the bot, post the one-time connect command the app shows in that chat.
7. When the app finds the chat, check that it posted the word you expect, then click Connect this chat. Click Check now if the chat hasn't appeared yet. The app deletes the command message once the chat is connected.

Add the MCP server to your AI client

Server URL: https://telegram.insightfulmcp.com/ and server name: telegram-mcp.

• Claude: open Claude Connectors Settings, scroll to the bottom and click Add custom connector, paste the URL, click Add, then click Connect.
• ChatGPT: in ChatGPT Security Settings turn on Developer mode, click Create on the Connectors page, paste the URL, click Create, then click Connect. Turn the connector on in each new chat with + → More.
• Claude Code: run claude mcp add --transport http telegram-mcp https://telegram.insightfulmcp.com/, then type /mcp, select telegram-mcp and click Authenticate.
• Cursor: in the app, open MCP Servers, choose Telegram and click Install Telegram MCP, click Open Cursor then Install, then click Connect and Open.
• Gemini CLI: run gemini mcp add --transport http telegram-mcp https://telegram.insightfulmcp.com/, then /mcp auth telegram-mcp.
• Codex CLI: run codex mcp add telegram-mcp --url https://telegram.insightfulmcp.com/; authorization starts automatically.

Each client opens a browser window where you log in to InsightfulPipe and click Authorize access. Step-by-step guides: Claude, ChatGPT, Claude Code, Cursor, Gemini CLI and Codex CLI. To reach every connected platform through one server, use the unified server.

Permissions and safety

• Read Only connections run reads only. Sending, editing, pinning and deleting need Read + Write.
• delete_message is destructive, so it stays off until an owner, admin or operator enables it in Configure actions for this account.
• Sending messages and unpin_all_chat_messages are regular write actions that are on for Read + Write connections. Posts go out to everyone in the chat.
• Connect a chat only if you recognise the word it posted. Anyone who can read the word could have posted it in another chat.
• Writes need the Owner, Administrator or Operator role. Members with the User role can only run enabled read actions on accounts granted to them.

Limits

• The connector acts as your bot, not your personal Telegram account, and only in the one chat you connected.
• There is no action to read chat history or incoming messages. Agents work with messages the bot sends, using the message IDs Telegram returns, and with messages you reference by ID.
• It can't manage members, change chat settings or message other chats.
• Send actions aren't retried automatically, to avoid duplicate posts.
• Telegram Bot API limits apply, including file size limits for media.

Example prompts

• "Using Telegram, post a short summary of this week's sales numbers to the channel."
• "Send a poll asking the team which day works for the launch call."
• "Send this product photo with the caption New arrivals."
• "Pin the announcement we just sent."

Troubleshooting

• The chat never appears after you post the command: check that the bot is an administrator of that chat, then post the command again. Anything posted before the bot joined is invisible to it.
• "This step expired." Click Start again and post the new command.
• The chat picker doesn't work: open Add bot to a chat from the Telegram desktop or phone app instead of the web version.
• "This action is disabled for this connected account. An owner or admin must enable it for the account." An owner, admin or operator can enable it in Configure actions for this account.
• "This account is connected read-only, so this action cannot be enabled for it. An owner or admin must reconnect it with Read & Write permissions." Reconnect and choose Read + Write under Permissions.

FAQ

Can the agent read messages in the chat?

No. There is no action for chat history. It can read the chat's details and member status, and work with messages the bot sent.

Can I use one bot in several chats?

Yes. Each connection is one bot in one chat, so connect the same bot to each chat separately. Each connection counts as one connection on your plan.

Related

• Telegram MCP server
• Slack connector
• Manage and move brand connections
• MCP troubleshooting