# 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
# Gemini CLI (YOLO mode - auto-approve all MCP calls)
gemini --yolo
# 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** đ
Raw data
{
"_id": null,
"home_page": null,
"name": "telegram-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "mcp, telegram, claude, ai, automation",
"author": null,
"author_email": "Ray Volcy <volycu@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ae/b3/76ea8386b9a8af292e9edf42fb1790778d5d8359dbf50e3417d70b0548e9/telegram_mcp_server-0.2.4.tar.gz",
"platform": null,
"description": "# Telegram MCP Server\n\n> Remote control AI coding assistants (Claude Code / Codex) via Telegram\n\n[](https://pypi.org/project/telegram-mcp-server/)\n[](https://pypi.org/project/telegram-mcp-server/)\n[](LICENSE)\n\nEnglish | [\u7b80\u4f53\u4e2d\u6587](README-CN.md)\n\n## Why This Project?\n\nHave you ever encountered these scenarios:\n\n- \ud83d\udca4 **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?\n- \ud83d\ude87 **On your commute**, you want AI to refactor code for you, but your laptop isn't with you?\n- \ud83c\udfe2 **Multiple Claude Code or Codex sessions** running on remote servers, and you want to check their progress anytime?\n- \u23f0 **Long-running tasks** (testing, building, refactoring) that take hours, but you don't want to sit in front of the computer?\n\n**Telegram MCP Server was created to solve these problems!**\n\nThrough the MCP (Model Context Protocol), this project allows you to:\n- \ud83d\udcf1 **Anytime, anywhere** view and control AI coding assistants via Telegram\n- \ud83d\udd04 **Multi-session management**: Use `screen` on remote servers to manage multiple projects simultaneously\n- \ud83c\udf19 **True unattended mode**: Wait up to 7 days with smart polling, minimal system resources\n- \ud83d\udcac **Simple interaction**: Send messages via Telegram to give AI assistants next instructions\n\n**Perfect for**:\n- 24/7 remote servers\n- Long-running tasks\n- Multi-project parallel development\n- Remote work from anywhere\n\n## Features\n\n- \ud83c\udf19 **True Unattended Mode** - Wait up to 7 days with smart progressive polling\n- \ud83d\udcf1 **Remote Control** - Control AI assistants from anywhere via Telegram\n- \ud83d\udd04 **Two-way Communication** - Send notifications, receive replies, continuous dialogue\n- \ud83d\udcc1 **File Operations** - View and download project files\n- \ud83c\udfaf **Multi-session Management** - Manage multiple projects simultaneously\n- \ud83e\udd16 **Universal Support** - Works with both Claude Code and Codex\n\n## \u26a1 Quick Start (New Users)\n\n### Installation & Setup (One Command)\n\n```bash\n# Use uvx (recommended, no installation needed, always latest version)\nuvx --refresh telegram-mcp-server@latest --setup\n```\n\nThis will:\n1. \u2705 Download the latest version from PyPI\n2. \u2705 Guide you through Telegram Bot setup\n3. \u2705 Auto-configure Claude Code / Codex / Gemini CLI\n4. \u2705 Test the connection\n\n**That's it!** \ud83c\udf89\n\n### Verify Installation\n\n```bash\n# Check version (should be 0.2.1 or higher)\nuvx telegram-mcp-server@latest --version\n```\n\n**Expected output**:\n```\ntelegram-mcp-server version 0.2.1\nhttps://github.com/batianVolyc/telegram-mcp-server\n```\n\n---\n\n## \ud83d\udcd6 Detailed Installation\n\n### Method 1: Using uvx (Recommended)\n\n```bash\n# Always use latest version\nuvx telegram-mcp-server@latest --setup\n\n# Or using pip\npip install telegram-mcp-server\n```\n\n### 2. Setup\n\n#### Option A: Automatic Setup (Recommended)\n\n```bash\ntelegram-mcp-server --setup\n```\n\nInteractive wizard will help you:\n- Create Telegram Bot\n- Get credentials\n- Auto-configure AI assistant\n\n#### Option B: Manual Setup with `mcp add`\n\nIf you already have your Telegram Bot Token and Chat ID, you can quickly add using the `mcp add` command:\n\n**Claude Code**:\n```bash\nclaude mcp add \\\n --transport stdio \\\n telegram \\\n --env TELEGRAM_BOT_TOKEN=YOUR_TOKEN_HERE \\\n --env TELEGRAM_CHAT_ID=YOUR_CHAT_ID_HERE \\\n -- \\\n uvx telegram-mcp-server\n```\n\n**Codex**:\n```bash\ncodex mcp add telegram \\\n --env TELEGRAM_BOT_TOKEN=YOUR_TOKEN_HERE \\\n --env TELEGRAM_CHAT_ID=YOUR_CHAT_ID_HERE \\\n -- \\\n npx -y telegram-mcp-server\n```\n\n**Gemini CLI**:\n```bash\ngemini mcp add telegram uvx telegram-mcp-server \\\n -e TELEGRAM_BOT_TOKEN=YOUR_TOKEN_HERE \\\n -e TELEGRAM_CHAT_ID=YOUR_CHAT_ID_HERE\n```\n\n> \ud83d\udca1 **Tip**: Replace `YOUR_TOKEN_HERE` and `YOUR_CHAT_ID_HERE` with your actual values\n\n### 3. Usage\n\n```bash\n# Recommended: Start with bypass permissions mode\n# Avoid interruptions due to permission confirmations during AI-Telegram interaction\n# Note: Cannot run as root due to security mechanisms\n\n# Claude Code\nclaude --permission-mode bypassPermissions\n\n# Codex\ncodex --dangerously-bypass-approvals-and-sandbox\n\n# Gemini CLI (YOLO mode - auto-approve all MCP calls)\ngemini --yolo\n\n# In the AI assistant\n> Enter unattended mode. Task: analyze project structure\n```\n\nCheck results in Telegram and continue the conversation!\n\n## How It Works\n\n```\nAI Assistant (Claude Code/Codex)\n \u2193 MCP Protocol\nMCP Server (telegram-mcp-server)\n \u251c\u2500 8 tools (notify, wait, file operations, etc.)\n \u2514\u2500 Telegram Bot (background process)\n \u2193 Telegram API\nYour Telegram Client\n```\n\n## Core Features\n\n### MCP Tools (8 tools)\n\n- `telegram_notify` - Send structured notifications (recommended)\n- `telegram_wait_reply` - Wait for user reply (blocking poll)\n- `telegram_unattended_mode` - Unattended mode (smart loop)\n- `telegram_send_code` - Send code (with syntax highlighting)\n- `telegram_send_image` - Send images\n- `telegram_send_file` - Send files\n- `telegram_send` - Send free-form messages\n- `telegram_get_context_info` - Get session context info\n\n### Telegram Commands (6 commands)\n\n- `/sessions` - List all sessions\n- `/status <id>` - Check session status\n- `/to <id> <msg>` - Send message to session\n- `/file <id> <path>` - View file\n- `/delete <id>` - Delete session\n- `/help` - Show help\n\n### Smart Polling\n\nProgressive polling strategy, wait up to 7 days:\n\n| Wait Time | Check Frequency | Response Delay |\n|-----------|----------------|----------------|\n| 0-30 min | Every 30s | Max 30s |\n| 30-60 min | Every 60s | Max 60s |\n| 1+ hour | Every 120s | Max 120s |\n\n## Use Cases\n\n### Scenario 1: Overnight Tasks\n\n```bash\n# 10 PM\n> Enter unattended mode. Task: run full test suite and fix all errors\n\n# 8 AM - check results in Telegram\n```\n\n### Scenario 2: Remote Work\n\n```bash\n# At office\n> Enter unattended mode. Task: refactor database access layer\n\n# On the road - monitor and control via Telegram\n```\n\n### Scenario 3: Multi-project Management (Remote Server + screen)\n\n```bash\n# SSH to remote server\nssh user@server\n\n# Create multiple screen sessions\nscreen -S project-a\ncd /path/to/project-a\nTELEGRAM_SESSION=\"proj-a\" claude --permission-mode bypassPermissions\n# Ctrl+A D to detach\n\nscreen -S project-b\ncd /path/to/project-b\nTELEGRAM_SESSION=\"proj-b\" codex --dangerously-bypass-approvals-and-sandbox\n# Ctrl+A D to detach\n\n# Manage both projects in Telegram\n# Sessions keep running even after closing SSH\n```\n\n### Scenario 4: Late Night in Bed\n\n```bash\n# During the day, start session on server\nscreen -S night-task\nTELEGRAM_SESSION=\"night-fix\" claude --permission-mode bypassPermissions\n\n# At night in bed, send commands via Telegram\n/to night-fix Fix null pointer exception in auth.py\n\n# Next morning, check results\n/status night-fix\n```\n\n## Configuration\n\n### Claude Code\n\nSupports three configuration scopes:\n\n**MCP Server Configuration**:\n- **User scope**: `~/.claude.json` - Global config\n- **Project scope**: `.mcp.json` - Team shared\n- **Local scope**: `.claude.json` - Project specific\n\n**Environment Variables** (auto-configured):\n- `~/.claude/settings.json` - Contains `MCP_TOOL_TIMEOUT=604800000` (7-day timeout)\n\n### Codex\n\nGlobal config: `~/.codex/config.toml`\n\nAuto-includes `tool_timeout_sec = 604800` (7 days timeout)\n\n## Environment Variables\n\n```bash\n# Custom session name\nTELEGRAM_SESSION=\"my-task\" claude\n\n# Custom max wait time\nTELEGRAM_MAX_WAIT=86400 claude # 24 hours\n\n# Custom poll intervals\nTELEGRAM_POLL_INTERVAL=\"10,30,60\" claude\n```\n\n## Troubleshooting\n\n### Issue: Telegram Bot Not Responding\n\n```bash\n# Check logs\ntail -f /tmp/telegram-mcp-server.log\n\n# Quick fix\ncd telegram-mcp-server\n./quick_fix.sh\n```\n\n### Issue: Codex 60s Timeout\n\n```bash\n# Auto fix\n./fix_codex_timeout.sh\n```\n\n### Issue: Session Not Registered\n\n```bash\n# Reconfigure\ntelegram-mcp-server --setup\n```\n\n## Documentation\n\n- [Configuration Guide](docs/CONFIGURATION_GUIDE.md) - Detailed configuration\n- [Polling Mechanism](docs/POLLING_MECHANISM.md) - Smart polling explained\n- [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues\n- [How MCP Works](docs/HOW_MCP_WORKS.md) - Technical architecture\n\n## Requirements\n\n- Python 3.10+\n- Claude Code or Codex\n- Telegram account\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](docs/CONTRIBUTING.md)\n\n## License\n\nMIT License - see [LICENSE](LICENSE)\n\n## Support\n\n- \ud83d\udc1b [Report Issues](https://github.com/batianVolyc/telegram-mcp-server/issues)\n- \ud83d\udcac [Discussions](https://github.com/batianVolyc/telegram-mcp-server/discussions)\n- \u2b50 Star if you find it useful!\n\n---\n\n**Let AI coding assistants work for you, not you waiting for them** \ud83d\ude80\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Remote control Claude Code via Telegram - MCP Server with Dynamic Buttons",
"version": "0.2.4",
"project_urls": {
"Documentation": "https://github.com/batianVolyc/telegram-mcp-server#readme",
"Homepage": "https://github.com/batianVolyc/telegram-mcp-server",
"Issues": "https://github.com/batianVolyc/telegram-mcp-server/issues",
"Repository": "https://github.com/batianVolyc/telegram-mcp-server"
},
"split_keywords": [
"mcp",
" telegram",
" claude",
" ai",
" automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "47723aa4b8a820b95561afc2ebb8839e831a175d62fa1c30ac62348fa8a18615",
"md5": "9a01a3838795afcf980410775d878805",
"sha256": "59929d39d68391c291f38391a85e2b867fb4f544c8ee73fab7ac44a402a163b2"
},
"downloads": -1,
"filename": "telegram_mcp_server-0.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9a01a3838795afcf980410775d878805",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 34103,
"upload_time": "2025-10-22T11:23:19",
"upload_time_iso_8601": "2025-10-22T11:23:19.124277Z",
"url": "https://files.pythonhosted.org/packages/47/72/3aa4b8a820b95561afc2ebb8839e831a175d62fa1c30ac62348fa8a18615/telegram_mcp_server-0.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "aeb376ea8386b9a8af292e9edf42fb1790778d5d8359dbf50e3417d70b0548e9",
"md5": "d9ee778d21b87b60ee47f1612fe3549b",
"sha256": "bcd6b5aaacbbfc7c2f77e9d2e575049e3c9914025829bf3e4ce3015f80025c65"
},
"downloads": -1,
"filename": "telegram_mcp_server-0.2.4.tar.gz",
"has_sig": false,
"md5_digest": "d9ee778d21b87b60ee47f1612fe3549b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 35530,
"upload_time": "2025-10-22T11:23:21",
"upload_time_iso_8601": "2025-10-22T11:23:21.302035Z",
"url": "https://files.pythonhosted.org/packages/ae/b3/76ea8386b9a8af292e9edf42fb1790778d5d8359dbf50e3417d70b0548e9/telegram_mcp_server-0.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-22 11:23:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "batianVolyc",
"github_project": "telegram-mcp-server#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "mcp",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "python-telegram-bot",
"specs": [
[
">=",
"21.0"
]
]
},
{
"name": "aiofiles",
"specs": [
[
">=",
"23.0.0"
]
]
}
],
"lcname": "telegram-mcp-server"
}
JSON
