Telegram MCP Server

Name: Telegram MCP Server
Author: chigwell

@chigwell

About Telegram MCP Server

Telegram MCP server powered by Telethon to let MCP clients read chats, manage groups, and send/modify messages, media, contacts, and settings.

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "uv",
      "args": [
        "sync"
      ]
    }
  }
}

Tools

No tools detected

We auto-extract tools from the README. The maintainer can list them under a ## Tools heading to populate this section.

Overview

What is Telegram MCP Server?

Telegram MCP Server is a Telegram integration for Claude, Cursor, and other MCP-compatible clients. It exposes Telegram account, chat, message, contact, media, folder, and admin operations through the Model Context Protocol (MCP) using Telethon.

How to use Telegram MCP Server?

Clone the repository, install dependencies with uv sync, generate a session string using uv run session_string_generator.py, configure environment variables in .env, and run with uv run main.py. For Claude Desktop or Cursor, point the MCP server at the cloned checkout and supply TELEGRAM_API_ID, TELEGRAM_API_HASH, and TELEGRAM_SESSION_STRING in the server’s env block. Docker is also supported.

Key features of Telegram MCP Server

80+ MCP tools for accounts, chats, messages, contacts, media, profile, folders, and drafts
Multi‑account support with per‑account session strings and labels
Read‑only mode to restrict tool exposure via TELEGRAM_EXPOSED_TOOLS
Proxy support (SOCKS5, SOCKS4, HTTP, MTProxy) with per‑account overrides
File path security with allowed roots and strict validation
Docker deployment with Compose or direct commands

Use cases of Telegram MCP Server

Let an AI assistant send, schedule, edit, or delete Telegram messages
Analyze chat history and have the assistant reply based on context
Manage multiple Telegram accounts from a single MCP client
Automate group/channel creation, member invitations, and admin actions
Download or upload media, send voice notes, stickers, and GIFs programmatically

FAQ from Telegram MCP Server

What are the requirements to run Telegram MCP Server?

Python 3.10+, Telegram API credentials from my.telegram.org/apps, a Telegram session string or file‑based session, and an MCP‑compatible client such as Claude Desktop or Cursor.

How do I enable read‑only mode?

Set the environment variable TELEGRAM_EXPOSED_TOOLS=read-only in the server configuration. This exposes only tools annotated with readOnlyHint=True; it does not reduce the Telegram session’s account permissions.

Can I use multiple Telegram accounts?

Yes. Use suffixed session variables such as TELEGRAM_SESSION_STRING_WORK and TELEGRAM_SESSION_STRING_PERSONAL. Labels become the account parameter in tools. Write tools require an account label; read‑only tools fan out to all accounts when omitted.

Does Telegram MCP Server support proxies?

Yes. Set TELEGRAM_PROXY_TYPE, TELEGRAM_PROXY_HOST, TELEGRAM_PROXY_PORT (and optional username/password). Supported types: socks5, socks4, http, mtproxy. Per‑account overrides use the same suffix as session variables.

How are file paths secured?

File‑path tools are disabled until allowed roots are configured, either as CLI arguments or via MCP client Roots. Paths are resolved to real paths and must stay inside an allowed root; traversal, wildcard, and null‑byte patterns are rejected.