home / mcp / telegram mcp server

Telegram MCP Server

Remote control AI coding assistants (Claude Code/Codex) via Telegram

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "batianvolyc-telegram-mcp-server": {
      "command": "telegram-mcp-server",
      "args": [
        "--setup"
      ],
      "env": {
        "TELEGRAM_CHAT_ID": "YOUR_CHAT_ID_HERE",
        "TELEGRAM_SESSION": "YOUR_SESSION_NAME",
        "TELEGRAM_MAX_WAIT": "86400",
        "TELEGRAM_BOT_TOKEN": "YOUR_TOKEN_HERE",
        "TELEGRAM_POLL_INTERVAL": "10,30,60"
      }
    }
  }
}

You can control Claude Code, Codex, or Gemini CLI AI coding assistants remotely via Telegram with the Telegram MCP Server. It enables multi-session management, unattended operation for long-running tasks, and two-way communication so you can monitor progress, send commands, and retrieve results from anywhere.

How to use

Set up your MCP client and connect it to the Telegram MCP Server to manage AI coding assistants from Telegram. Use Telegram to start new sessions, monitor progress, send instructions, view project files, and receive notifications. You can run multiple projects on a single remote server using screen sessions, keep tasks running after you disconnect, and gradually poll for results over days without keeping the terminal open.

How to install

Prerequisites you need before installing:

# Prerequisites
- Python 3.10+
- Telegram account
- Claude Code or Codex (or Gemini CLI) for integration
- Internet access for Telegram bot setup

Concrete installation steps you can follow exactly as shown here:

# Recommended: install via uvx to always get the latest version and setup in one go
uvx --refresh telegram-mcp-server@latest --setup

# Verify installation (should show a version such as 0.2.1+)
uvx telegram-mcp-server@latest --version

If you prefer a direct Python package install, you can also install with pip and then run the setup flow.

pip install telegram-mcp-server
telegram-mcp-server --setup

After you run setup, you will configure the Telegram Bot credentials and the AI assistant integration. You will also test the connection to ensure the bot can talk to your AI backend.

Configuration and runtime commands

You can run the MCP server in different ways depending on your workflow. The following approaches are shown in the setup flow and usage examples.

# Run the MCP server directly via the Telegram CLI (unattended mode is configured via the assistant side)
telegram-mcp-server --setup

If you want to run the MCP server using a package runner that auto-installs the server, you can use npx or uvx as shown in the examples below.

# Run via npx (local npm registry) in the terminal
npx -y telegram-mcp-server

# Run via uvx (latest version, with automatic setup)
uvx telegram-mcp-server@latest --setup

For quick integration with Claude Code or Codex, you can add a client MCP entry that points to how to start the server in your environment. Examples include integrating via your preferred CLI and letting the MCP server manage the Telegram session.

Configuration and environment variables

The following environment variables are used to connect the MCP server to Telegram and to customize the unattended behavior.

TELEGRAM_BOT_TOKEN=YOUR_TOKEN_HERE
TELEGRAM_CHAT_ID=YOUR_CHAT_ID_HERE

# Optional per-session overrides
TELEGRAM_SESSION="my-task"
TELEGRAM_MAX_WAIT=86400      # seconds (example: 24 hours)
TELEGRAM_POLL_INTERVAL="10,30,60"  # seconds

Tools and capabilities

The server exposes a set of tools to interact with your AI assistants and manage sessions. These tools enable notifications, waiting for replies, unattended operation, sending code or files, and querying session context.

Troubleshooting

If you encounter issues with the Telegram bot or session registration, check the logs and reconfigure the setup if needed.

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

# Reconfigure (if needed)
telegram-mcp-server --setup

Notes

Progress is handled through smart polling that can wait for results over an extended period, so you can start a long-running task and monitor it from Telegram without keeping your terminal open.

Available tools

telegram_notify

Send structured notifications to you from the MCP server, including progress updates and results.

telegram_wait_reply

Wait for a user reply via Telegram before continuing with the next step.

telegram_unattended_mode

Operate in unattended mode with smart polling to handle long-running tasks.

telegram_send_code

Send code snippets with syntax highlighting to your Telegram chat.

telegram_send_image

Send images through the Telegram channel to show outputs or visual results.

telegram_send_file

Send files from your project directory to Telegram for quick reference.

telegram_send

Send free-form messages to Telegram from the MCP server.

telegram_get_context_info

Retrieve current session context information for debugging or progress tracking.