Telegram Bridge

You can bridge your AI assistant with a Telegram bot to enable two-way messaging, live status updates, and voice transcription, all while keeping your setup private and free from public webhooks. This MCP server lets your AI host communicate with Telegram in real time, so you can send messages, receive responses, and manage interactions directly from your preferred AI environment.

How to use

Connect this MCP server to your preferred MCP client (such as VS Code Copilot or Claude Desktop) and pair it with your Telegram bot. Once connected, your assistant can message your Telegram chat, ask for input with text or button options, post live status checklists, react to messages with emoji, and transcribe voice replies into text. All interactions are delivered in real time without the need for public URLs or webhooks.

How to install

Prerequisites you need before starting:

If you prefer npm, you can substitute npm for pnpm commands.

Step by step setup:

git clone https://github.com/electricessence/Telegram-Bridge-MCP.git
cd Telegram-Bridge-MCP
pnpm install
pnpm build

Configuration and setup notes

Create and configure your Telegram bot to obtain a token, then pair the bot to your MCP environment to generate a one-time pairing code and map your Telegram chat to an allowed user. You’ll store the bot token and IDs in your environment file for your MCP host.

Security

This server uses a two-layer security model to protect interactions. Inbound updates are checked against a specific allowed user ID, and outbound tool calls are restricted to an allowed chat ID. The setup is designed for single-user, single-chat usage, with the chat ID resolved from your configuration.

Voice transcription

All incoming message tools can transcribe voice messages locally using a Whisper model via ONNX Runtime, with no external API calls required and no ffmpeg dependency. We cache model weights after the first use.

Development

If you are modifying or extending the MCP server, you can build, run tests, and start a development cycle with these commands.

pnpm build
pnpm dev
pnpm test
pnpm coverage
pnpm pair

Available tools

get_agent_guide

Loads the behavioral guide for how the AI agent should operate for the session start.

notify

Produce a notification with a title, body, and severity level, either silently or audibly.

ask

Send a question and wait for the user to reply with text.

choose

Ask a question with multiple button options and wait for the user to tap one.

send_confirmation

Prompt Yes/No against a callback mechanism to capture confirmation.

update_status

Display a live in-place checklist that updates as steps complete.

send_message

Send a message to the Telegram chat; supports text, Markdown, and media.

edit_message_text

Edit a previously sent message in the Telegram chat.

forward_message

Forward a Telegram message to another chat.

delete_message

Delete a message in the Telegram chat.

pin_message

Pin a message in the Telegram chat.

send_chat_action

Indicate activity in the Telegram chat (e.g., typing).

start_typing

Show that the assistant is typing in the chat.

wait_for_message

Block until a message arrives from the user and return its content.

wait_for_callback_query

Block until the user taps a button and return the chosen value.

answer_callback_query

Respond to a button press to acknowledge the user action.

get_me

Retrieve information about the bot.

get_chat

Fetch information about a Telegram chat.

set_reaction

Apply a reaction emoji to a message.

get_updates

Poll for updates from Telegram.

restart_server

Restart the MCP server process.