telegram

This Telegram MCP Server lets you remote-control AI coding assistants (Claude Code, Codex, Gemini CLI) via Telegram. It runs as a background MCP server that exposes a set of tools and Telegram commands to manage multiple sessions and interact with AI assistants remotely. You can start unattended sessions, monitor progress through Telegram, and perform file operations or send code and files back and forth. The core idea is to enable true unattended operation with smart polling, so long-running tasks can proceed on a remote server while you monitor and guide them from your Telegram client. The server supports multi-session management, two-way communication, and a suite of MCP tools specifically designed for Telegram-based control and feedback.

Prerequisites:

• Python installed on the host (the server runs as a Python package).
• Internet access to fetch the telegram-mcp-server package.
• Optionally uvx (recommended) for easy management of versions.

Installation steps:

1. Install uvx (optional but recommended) and install the Telegram MCP Server:

# Install uvx if you don't have it
pip install uvx

# Install and setup the Telegram MCP Server (latest)
uvx --refresh telegram-mcp-server@latest --setup

2. If you prefer direct Python/pip setup:

pip install telegram-mcp-server

3. Run the MCP server (example using uvx):

uvx telegram-mcp-server@latest

4. During initial setup, follow prompts to create a Telegram Bot and configure credentials. You can also manually add a session later using the mcp add workflow described in the documentation.

Tips and notes:

• Set up TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID in your environment or via the mcp add flow to connect to your Telegram bot and chat.
• The server supports unattended mode with progressive polling up to 7 days; adjust TELEGRAM_MAX_WAIT and TELEGRAM_POLL_INTERVAL if needed.
• For reliability, run the MCP server inside a persistent process manager (e.g., screen, tmux, or systemd) on a remote server.
• Common issues: ensure the Telegram bot has the proper permissions and that network access to Telegram servers is allowed. If the bot stops responding, check logs at /tmp/telegram-mcp-server.log or run quick_fix.sh if available in the repo.
• You can manage multiple sessions across projects using screen sessions and a Telegram interface to monitor status and issue commands.
• Environment variable tips: TELEGRAM_SESSION can customize per-session names; TELEGRAM_MAX_WAIT and TELEGRAM_POLL_INTERVAL can tune timeout and polling cadence.