README.md•8.72 kB
# Telegram MCP Server
> Remote control AI coding assistants (Claude Code / Codex) via Telegram
[](https://pypi.org/project/telegram-mcp-server/)
[](https://pypi.org/project/telegram-mcp-server/)
[](LICENSE)
English | [简体中文](README-CN.md)
## 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 `screen` on 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)
```bash
# Use uvx (recommended, no installation needed, always latest version)
uvx --refresh telegram-mcp-server@latest --setup
```
This will:
1. ✅ Download the latest version from PyPI
2. ✅ Guide you through Telegram Bot setup
3. ✅ Auto-configure Claude Code / Codex / Gemini CLI
4. ✅ Test the connection
**That's it!** 🎉
### Verify Installation
```bash
# 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
```
---
## 📖 Detailed Installation
### Method 1: Using uvx (Recommended)
```bash
# Always use latest version
uvx telegram-mcp-server@latest --setup
# Or using pip
pip install telegram-mcp-server
```
### 2. Setup
#### Option A: Automatic Setup (Recommended)
```bash
telegram-mcp-server --setup
```
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**:
```bash
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**:
```bash
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**:
```bash
gemini mcp add telegram uvx telegram-mcp-server \
-e TELEGRAM_BOT_TOKEN=YOUR_TOKEN_HERE \
-e TELEGRAM_CHAT_ID=YOUR_CHAT_ID_HERE
```
> 💡 **Tip**: Replace `YOUR_TOKEN_HERE` and `YOUR_CHAT_ID_HERE` with your actual values
### 3. Usage
```bash
# 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
# In the AI assistant
> Enter unattended mode. Task: analyze project structure
```
Check results in Telegram and continue the conversation!
## 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:
| 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
```bash
# 10 PM
> Enter unattended mode. Task: run full test suite and fix all errors
# 8 AM - check results in Telegram
```
### Scenario 2: Remote Work
```bash
# 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)
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Check logs
tail -f /tmp/telegram-mcp-server.log
# Quick fix
cd telegram-mcp-server
./quick_fix.sh
```
### Issue: Codex 60s Timeout
```bash
# Auto fix
./fix_codex_timeout.sh
```
### Issue: Session Not Registered
```bash
# Reconfigure
telegram-mcp-server --setup
```
## Documentation
- [Configuration Guide](docs/CONFIGURATION_GUIDE.md) - Detailed configuration
- [Polling Mechanism](docs/POLLING_MECHANISM.md) - Smart polling explained
- [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues
- [How MCP Works](docs/HOW_MCP_WORKS.md) - Technical architecture
## Requirements
- Python 3.10+
- Claude Code or Codex
- Telegram account
## Contributing
Contributions welcome! See [CONTRIBUTING.md](docs/CONTRIBUTING.md)
## License
MIT License - see [LICENSE](LICENSE)
## Support
- 🐛 [Report Issues](https://github.com/batianVolyc/telegram-mcp-server/issues)
- 💬 [Discussions](https://github.com/batianVolyc/telegram-mcp-server/discussions)
- ⭐ Star if you find it useful!
---
**Let AI coding assistants work for you, not you waiting for them** 🚀