Telegram

Enables interactive, human-in-the-loop decisions by delivering AI prompts via Telegram and handling responses.

python

0

GitHub Stars

python

Language

4 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "stoypenny-mcp-kilo-telegram": {
      "command": "python",
      "args": [
        "telegram_server.py"
      ],
      "env": {
        "TELEGRAM_USER_ID": "your_user_id_here",
        "TELEGRAM_BOT_TOKEN": "your_bot_token_here"
      }
    }
  }
}

You can run a Telegram-based MCP Server that lets an AI ask you questions and wait for your responses, enabling a human-in-the-loop workflow for long-running tasks. It supports interactive questions with optional buttons, works with any MCP-compatible AI assistant, and can run natively with Python or inside Docker.

How to use

Set up the server and connect it to your MCP client. When the AI needs input or a decision, it will ask you via Telegram. You can respond directly in Telegram, or use the provided buttons for quick selections. Your responses are sent back to the AI so it can continue its work. Use non-blocking mode for complex questions to avoid timeouts and opt into progress notifications for long-running tasks.

How to install

Prerequisites you need to prepare before installing are listed here so you can choose the installation method that best fits your environment.

Native Python Installation steps you can follow on your system.

Docker Installation steps you can follow to run the server in a container.

Configuration

Configure credentials and environment settings using a .env file. The server uses a Telegram bot token and your Telegram user ID to identify who can respond to prompts.

Two environment variables you will typically provide are TELEGRAM_BOT_TOKEN and TELEGRAM_USER_ID. The token is issued by BotFather for your Telegram bot, and the user ID identifies who is allowed to respond to the bot.

For local testing, you will start the server using a Python command that runs the main script. When running in Docker, you will provide the same credentials via the environment file used by Docker.

Security and best practices

Never commit credential files to version control. Keep your .env file gitignored and use separate credentials for production. Use Docker secrets or other secret-management mechanisms for production deployments. Restrict access to the Telegram bot and keep the bot token secret.

If you plan to host multiple MCP servers, use separate credentials and environment configurations for each server to avoid cross-access between different bots or users.

Troubleshooting

If you encounter issues starting the server, verify Python is available or that Docker is properly installed and configured. Ensure the .env file exists and contains the required variables. Check that the Telegram bot token is valid and that you have started the bot with /start so it can message you.

If Telegram messages aren’t arriving, confirm that the Telegram user ID matches the configured value and that the bot has permission to message that user. Review logs for error details and ensure the server has network access to Telegram’s API.

Notes

This server supports interactive questions with optional button choices and a long-polling wait of up to two minutes for a response. You can switch between blocking and non-blocking modes depending on the complexity of the question and your availability.

Available tools

ask_human

Send questions to Telegram and optionally present multiple button choices. Supports blocking (wait for response) or non-blocking modes and returns the user’s answer to the AI.

get_telegram_response

Retrieve the latest Telegram message from the configured chat. Use after ask_human with non-blocking mode to obtain the response.

send_telegram_notification

Send one-way status updates to Telegram for progress or completion notifications without expecting a response.

list_telegram_messages

View recent Telegram conversation history to provide context for ongoing interactions.