Telegram MCP Server

🚀 Telegram MCP Server

This project enables remote control of AI coding assistants (Claude Code / Codex) via Telegram.

English | 简体中文

🚀 Quick Start

Installation & Setup (One Command)

# Use uvx (recommended, no installation needed, always latest version)
uvx --refresh telegram-mcp-server@latest --setup

This single command will:

1. ✅ Download the latest version from PyPI.
2. ✅ Guide you through setting up your Telegram Bot.
3. ✅ Automatically configure Claude Code / Codex / Gemini CLI.
4. ✅ Test the connection.

That's all! 🎉

Verify Installation

# Check version (should be 0.2.1 or higher)
uvx telegram-mcp-server@latest --version

Expected output:

telegram-mcp-server version 0.2.1
https://github.com/batianVolyc/telegram-mcp-server

✨ Features

• 🌙 True Unattended Mode: Wait up to 7 days with smart progressive polling.
• 📱 Remote Control: Control AI assistants from anywhere via Telegram.
• 🔄 Two-way Communication: Send notifications, receive replies, and have continuous dialogues.
• 📁 File Operations: View and download project files.
• 🎯 Multi-session Management: Manage multiple projects simultaneously.
• 🤖 Universal Support: Works with both Claude Code and Codex.

📦 Installation Guide

Method 1: Using uvx (Recommended)

# Always use latest version
uvx telegram-mcp-server@latest --setup

# Or using pip
pip install telegram-mcp-server

Setup

Option A: Automatic Setup (Recommended)

telegram-mcp-server --setup

The interactive wizard will assist you in:

• Creating a Telegram Bot.
• Obtaining credentials.
• Automatically configuring the AI assistant.

Option B: Manual Setup with mcp add

If you already have your Telegram Bot Token and Chat ID, you can use the mcp add command:

Claude Code:

claude mcp add \
  --transport stdio \
  telegram \
  --env TELEGRAM_BOT_TOKEN=YOUR_TOKEN_HERE \
  --env TELEGRAM_CHAT_ID=YOUR_CHAT_ID_HERE \
  -- \
  uvx telegram-mcp-server

Codex:

codex mcp add telegram \
  --env TELEGRAM_BOT_TOKEN=YOUR_TOKEN_HERE \
  --env TELEGRAM_CHAT_ID=YOUR_CHAT_ID_HERE \
  -- \
  npx -y telegram-mcp-server

Gemini CLI:

gemini mcp add telegram uvx telegram-mcp-server \
  -e TELEGRAM_BOT_TOKEN=YOUR_TOKEN_HERE \
  -e TELEGRAM_CHAT_ID=YOUR_CHAT_ID_HERE

💡 Usage Tip: Replace YOUR_TOKEN_HERE and YOUR_CHAT_ID_HERE with your actual values.

Usage

# Recommended: Start with bypass permissions mode
# Avoid interruptions due to permission confirmations during AI-Telegram interaction
# Note: Cannot run as root due to security mechanisms

# Claude Code
claude --permission-mode bypassPermissions

# Codex
codex --dangerously-bypass-approvals-and-sandbox

# Gemini CLI (YOLO mode - auto-approve all MCP calls)
gemini --yolo

# In the AI assistant
> Enter unattended mode. Task: analyze project structure

Check the results in Telegram and continue the conversation!

💻 Usage Examples

Basic Usage

# Start a task in unattended mode
claude --permission-mode bypassPermissions
> Enter unattended mode. Task: run full test suite and fix all errors

Advanced Usage

# Use custom environment variables
TELEGRAM_SESSION="my-task" TELEGRAM_MAX_WAIT=86400 claude --permission-mode bypassPermissions

📚 Documentation

How It Works

AI Assistant (Claude Code/Codex)
  ↓ MCP Protocol
MCP Server (telegram-mcp-server)
  ├─ 8 tools (notify, wait, file operations, etc.)
  └─ Telegram Bot (background process)
      ↓ Telegram API
Your Telegram Client

Core Features

MCP Tools (8 tools)

• telegram_notify: Send structured notifications (recommended).
• telegram_wait_reply: Wait for user reply (blocking poll).
• telegram_unattended_mode: Unattended mode (smart loop).
• telegram_send_code: Send code (with syntax highlighting).
• telegram_send_image: Send images.
• telegram_send_file: Send files.
• telegram_send: Send free-form messages.
• telegram_get_context_info: Get session context info.

Telegram Commands (6 commands)

• /sessions: List all sessions.
• /status <id>: Check session status.
• /to <id> <msg>: Send message to session.
• /file <id> <path>: View file.
• /delete <id>: Delete session.
• /help: Show help.

Smart Polling

Progressive polling strategy, wait up to 7 days:

Use Cases

Scenario 1: Overnight Tasks

# 10 PM
> Enter unattended mode. Task: run full test suite and fix all errors

# 8 AM - check results in Telegram

Scenario 2: Remote Work

# At office
> Enter unattended mode. Task: refactor database access layer

# On the road - monitor and control via Telegram

Scenario 3: Multi-project Management (Remote Server + screen)

# SSH to remote server
ssh user@server

# Create multiple screen sessions
screen -S project-a
cd /path/to/project-a
TELEGRAM_SESSION="proj-a" claude --permission-mode bypassPermissions
# Ctrl+A D to detach

screen -S project-b
cd /path/to/project-b
TELEGRAM_SESSION="proj-b" codex --dangerously-bypass-approvals-and-sandbox
# Ctrl+A D to detach

# Manage both projects in Telegram
# Sessions keep running even after closing SSH

Scenario 4: Late Night in Bed

# During the day, start session on server
screen -S night-task
TELEGRAM_SESSION="night-fix" claude --permission-mode bypassPermissions

# At night in bed, send commands via Telegram
/to night-fix Fix null pointer exception in auth.py

# Next morning, check results
/status night-fix

Configuration

Claude Code

Supports three configuration scopes:

• MCP Server Configuration:
  • User scope: ~/.claude.json - Global config.
  • Project scope: .mcp.json - Team shared.
  • Local scope: .claude.json - Project specific.
• Environment Variables (auto-configured):
  • ~/.claude/settings.json - Contains MCP_TOOL_TIMEOUT = 604800000 (7-day timeout).

Codex

Global config: ~/.codex/config.toml. Auto-includes tool_timeout_sec = 604800 (7 days timeout).

Environment Variables

# Custom session name
TELEGRAM_SESSION="my-task" claude

# Custom max wait time
TELEGRAM_MAX_WAIT=86400 claude  # 24 hours

# Custom poll intervals
TELEGRAM_POLL_INTERVAL="10,30,60" claude

Troubleshooting

Issue: Telegram Bot Not Responding

# Check logs
tail -f /tmp/telegram-mcp-server.log

# Quick fix
cd telegram-mcp-server
./quick_fix.sh

Issue: Codex 60s Timeout

# Auto fix
./fix_codex_timeout.sh

Issue: Session Not Registered

# Reconfigure
telegram-mcp-server --setup

More Documentation

• Configuration Guide - Detailed configuration.
• Polling Mechanism - Smart polling explained.
• Troubleshooting - Common issues.
• How MCP Works - Technical architecture.

🔧 Technical Details

Requirements

• Python 3.10+
• Claude Code or Codex
• Telegram account

📄 License

This project is under the MIT License - see LICENSE for details.

Support

• 🐛 Report Issues
• 💬 Discussions
• ⭐ Star if you find it useful!

Let AI coding assistants work for you, not you waiting for them 🚀