This server enables remote control and monitoring of AI coding assistants (Claude Code, Codex, Gemini CLI) via Telegram, allowing you to manage long-running development tasks from anywhere.
Core Features:
Structured Notifications: Send event-based updates (completed/error/question/progress) with summaries and details using
telegram_notifyTwo-way Communication: Wait for user replies with intelligent progressive polling (30s → 60s → 120s intervals, up to 7 days) via
telegram_wait_replyUnattended Mode: Run long-running tasks in a smart loop where the AI executes, reports results, and waits for next instructions using
telegram_unattended_modeFile Operations: Share code snippets with syntax highlighting (
telegram_send_code), project files (telegram_send_file), and images/visualizations (telegram_send_image)Session Management: Manage multiple AI assistant sessions simultaneously using environment variables and screen sessions
Context Information: Retrieve session details including token usage, runtime, system info, and project paths via
telegram_get_context_infoSimple Messaging: Send free-form messages with
telegram_sendwhen unstructured communication is needed
Use Cases: Run overnight tasks, manage multiple projects on remote servers, control AI assistants while away from your computer, and handle hours-long tasks without constant supervision.
Provides comprehensive Telegram Bot integration with tools for sending messages, files, images, code snippets, and managing two-way communication sessions with smart polling mechanisms
Telegram MCP Server
Remote control AI coding assistants (Claude Code / Codex) via Telegram
English | 简体中文
Why This Project?
Have you ever encountered these scenarios:
💤 Late at night in bed, you suddenly think of a bug that needs fixing, but don't want to get up and open your laptop?
🚇 On your commute, you want AI to refactor code for you, but your laptop isn't with you?
🏢 Multiple Claude Code or Codex sessions running on remote servers, and you want to check their progress anytime?
⏰ Long-running tasks (testing, building, refactoring) that take hours, but you don't want to sit in front of the computer?
Telegram MCP Server was created to solve these problems!
Through the MCP (Model Context Protocol), this project allows you to:
📱 Anytime, anywhere view and control AI coding assistants via Telegram
🔄 Multi-session management: Use
screenon remote servers to manage multiple projects simultaneously🌙 True unattended mode: Wait up to 7 days with smart polling, minimal system resources
💬 Simple interaction: Send messages via Telegram to give AI assistants next instructions
Perfect for:
24/7 remote servers
Long-running tasks
Multi-project parallel development
Remote work from anywhere
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, continuous dialogue
📁 File Operations - View and download project files
🎯 Multi-session Management - Manage multiple projects simultaneously
🤖 Universal Support - Works with both Claude Code and Codex
⚡ Quick Start (New Users)
Installation & Setup (One Command)
This will:
✅ Download the latest version from PyPI
✅ Guide you through Telegram Bot setup
✅ Auto-configure Claude Code / Codex / Gemini CLI
✅ Test the connection
That's it! 🎉
Verify Installation
Expected output:
📖 Detailed Installation
Method 1: Using uvx (Recommended)
2. Setup
Option A: Automatic Setup (Recommended)
Interactive wizard will help you:
Create Telegram Bot
Get credentials
Auto-configure AI assistant
Option B: Manual Setup with mcp add
If you already have your Telegram Bot Token and Chat ID, you can quickly add using the mcp add command:
Claude Code:
Codex:
Gemini CLI:
💡 Tip: Replace
YOUR_TOKEN_HEREandYOUR_CHAT_ID_HEREwith your actual values
3. Usage
Check results in Telegram and continue the conversation!
How It Works
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 imagestelegram_send_file- Send filestelegram_send- Send free-form messagestelegram_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:
Wait Time | Check Frequency | Response Delay |
0-30 min | Every 30s | Max 30s |
30-60 min | Every 60s | Max 60s |
1+ hour | Every 120s | Max 120s |
Use Cases
Scenario 1: Overnight Tasks
Scenario 2: Remote Work
Scenario 3: Multi-project Management (Remote Server + screen)
Scenario 4: Late Night in Bed
Configuration
Claude Code
Supports three configuration scopes:
MCP Server Configuration:
User scope:
~/.claude.json- Global configProject scope:
.mcp.json- Team sharedLocal scope:
.claude.json- Project specific
Environment Variables (auto-configured):
~/.claude/settings.json- ContainsMCP_TOOL_TIMEOUT=604800000(7-day timeout)
Codex
Global config: ~/.codex/config.toml
Auto-includes tool_timeout_sec = 604800 (7 days timeout)
Environment Variables
Troubleshooting
Issue: Telegram Bot Not Responding
Issue: Codex 60s Timeout
Issue: Session Not Registered
Documentation
Configuration Guide - Detailed configuration
Polling Mechanism - Smart polling explained
Troubleshooting - Common issues
How MCP Works - Technical architecture
Requirements
Python 3.10+
Claude Code or Codex
Telegram account
Contributing
Contributions welcome! See CONTRIBUTING.md
License
MIT License - see LICENSE
Support
⭐ Star if you find it useful!
Let AI coding assistants work for you, not you waiting for them 🚀