Telegram MCP Server

Telegram MCP Server

A Model Context Protocol (MCP) server that enables AI assistants (like Kilo Code) to ask you questions via Telegram and wait for your responses. This creates a "human-in-the-loop" workflow where the AI can request decisions, approvals, or specific input during long-running tasks.

Features

• 🤖 Interactive AI Workflow: AI can pause and ask you questions via Telegram
• 📱 Button Support: Present multiple choice options as clickable buttons
• ⏱️ Long Polling: Waits up to 2 minutes for your response
• 🔒 Secure: Uses environment variables for credentials
• 🎯 Simple Integration: Works with any MCP-compatible AI assistant
• 🐳 Docker Support: Run natively or in a container

Prerequisites

• Python 3.10+ (for native installation)
• OR Docker and Docker Compose (for containerized installation)
• A Telegram account
• A Telegram Bot Token (from @BotFather)

Installation Methods

You can run this MCP server in two ways:

1. Native Python Installation - Run directly on your system
2. Docker Installation - Run in a container (recommended for production)

Native Installation

1. Create a Telegram Bot

1. Open Telegram and search for @BotFather
2. Send /newbot and follow the prompts
3. Name your bot (e.g., "MyDevBot")
4. Copy the HTTP API Token provided
5. Important: Send /start to your new bot so it can message you

2. Find Your Telegram User ID (Optional)

1. Search for @userinfobot on Telegram
2. Send it any message
3. Copy your User ID

3. Clone and Setup

# Clone the repository
git clone https://github.com/yourusername/telegram-mcp-server.git
cd telegram-mcp-server

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate  # On Linux/Mac
# OR
venv\Scripts\activate  # On Windows

# Install dependencies
pip install -r requirements.txt

4. Configuration

Create a .env file from the sample:

cp .env.sample .env

Edit .env and add your credentials:

TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_USER_ID=your_user_id_here  # Optional - bot will auto-detect if not set

⚠️ Security Note: The .env file is gitignored to protect your credentials.

5. Test the Server Locally

# Activate virtual environment
source venv/bin/activate

# Run the server
python telegram_server.py

You should see:

╭──────────────────────────────────────────────────────────────────────────────╮
│                         ▄▀▀ ▄▀█ █▀▀ ▀█▀ █▀▄▀█ █▀▀ █▀█                        │
│                         █▀  █▀█ ▄▄█  █  █ ▀ █ █▄▄ █▀▀                        │
│                                FastMCP 2.14.2                                │
│                    🖥  Server:      Telegram Human Loop                       │
╰──────────────────────────────────────────────────────────────────────────────╯

Press Ctrl+C to stop the test.

Docker Installation

1. Configure Environment

cp .env.sample .env
# Edit .env with your credentials

2. Build and Run

# Build the Docker image
docker-compose build

# Start the container in detached mode
docker-compose up -d

3. View Logs

docker-compose logs -f telegram-mcp

4. Stop the Server

docker-compose down

Docker Commands Reference

Building:

# Build the image
docker-compose build

# Build without cache (force rebuild)
docker-compose build --no-cache

Running:

# Start in detached mode (background)
docker-compose up -d

# Start in foreground (see logs directly)
docker-compose up

# Start and rebuild if needed
docker-compose up -d --build

Monitoring:

# View logs
docker-compose logs -f telegram-mcp

# View last 100 lines of logs
docker-compose logs --tail=100 telegram-mcp

# Check container status
docker-compose ps

# Execute commands inside the container
docker-compose exec telegram-mcp python --version

Stopping and Cleaning:

# Stop the container
docker-compose stop

# Stop and remove containers
docker-compose down

# Stop, remove containers, and remove volumes
docker-compose down -v

# Remove all (containers, networks, images)
docker-compose down --rmi all

Restart:

# Restart the container
docker-compose restart

# Rebuild and restart from scratch
docker-compose down
docker-compose build --no-c