✈️ Telegram User MCP

Production-Grade Model Context Protocol (MCP) Server for Full Personal Telegram Account (Userbot / MTProto) Control via Telethon & FastMCP

🇺🇸 English | 🇷🇺 Русский | 🇨🇳 中文

Overview  •  System Architecture  •  MCP Tools  •  Quick Start  •  Configuration

🇺🇸 Overview

Telegram User MCP is a high-performance, asynchronous Model Context Protocol (MCP) server engineered in Python using FastMCP and Telethon. Unlike standard Bot API integrations that are restricted to bot accounts and limited group visibility, Telegram User MCP connects directly to Telegram's native MTProto API on behalf of a personal user account (Userbot).

This grants AI assistants (Claude Desktop, Cursor, Goose, Windsurf) seamless, structured access to your personal chats, private groups, channels, saved messages, global search, and message management over local stdio with zero third-party cloud relays.

Related MCP server: Telegram MCP Server

🧠 System Architecture

Telegram User MCP enforces strict separation between JSON-RPC Stdio Transport, Resilient Error & Rate-Limit Middleware, Entity Resolution & Peer Cache, and MTProto Session Management.

flowchart TD
    subgraph Clients ["1. AI Host Clients (Local Stdio)"]
        CLAUDE["Claude Desktop"]
        CURSOR["Cursor IDE"]
        GOOSE["Block Goose / Windsurf"]
    end

    subgraph MCPServer ["2. FastMCP Server Layer (server.py)"]
        STDIO["Pure JSON-RPC Stdio Transport (stderr-isolated logging)"]
        TOOLS["7 Strictly-Typed Async MCP Tools"]
        SAFE["Resilient Execution Wrapper (_execute_safely)"]
    end

    subgraph CoreEngine ["3. Telethon MTProto Client Manager"]
        LIFESPAN["Async Lifespan Singleton & Lock"]
        RESOLVER["Smart Entity Resolver (int ID / @username / 'me')"]
        WARMUP["Auto StringSession Dialog Cache Warm-up"]
        FLOOD["FloodWait Auto-Sleep & Retry Guard"]
    end

    subgraph AuthLayer ["4. Auth & Storage (.env / auth.py)"]
        AUTH_CLI["Interactive CLI Wizard (auth.py + 2FA Support)"]
        STR_SESS["In-Memory StringSession / Local .session"]
        TG_CLOUD["Telegram MTProto Cloud DCs"]
    end

    CLAUDE & CURSOR & GOOSE <-->|JSON-RPC 2.0 over stdio| STDIO
    STDIO --> TOOLS
    TOOLS --> SAFE
    SAFE --> FLOOD
    FLOOD --> LIFESPAN
    LIFESPAN --> RESOLVER
    RESOLVER -.->|Cache Miss Fallback| WARMUP
    AUTH_CLI -->|Generates TELEGRAM_SESSION_STRING| STR_SESS
    LIFESPAN --> STR_SESS
    LIFESPAN <-->|Encrypted MTProto TCP| TG_CLOUD

✨ Key Features

• 🔐 Native Personal Account Control (MTProto): Full access to personal dialogs, archived folders, private supergroups, channels, and Saved Messages (me).

• 🛡️ Zero Stdio Pollution: All server and Telethon diagnostic logs are strictly routed to sys.stderr, guaranteeing 100% corruption-free JSON-RPC 2.0 communication over stdout.

• ⚡ Smart StringSession Entity Resolution: Automatically resolves numeric peer IDs (-100..., 12345678), stringified numbers, @usernames, and 'me'. Includes automatic dialog cache warm-up when access_hash entries are cold in StringSession.

• ⏱️ Adaptive FloodWaitError Recovery: Automatically sleeps and retries transient rate limits (up to TELEGRAM_MAX_FLOOD_WAIT_SLEEP=15s) while returning structured retry telemetry for longer blocks without crashing the server.

• 🔑 One-Time Interactive 2FA Auth Wizard (auth.py): Standalone CLI utility supporting SMS/App codes and hidden cloud 2FA passwords (getpass), automatically exporting TELEGRAM_SESSION_STRING directly into .env.

• 🧱 Strict Pydantic Validation & Typing: Comprehensive parameter bounds checking (limit, offset_id, folder, message_id) and structured JSON schemas for reliable LLM tool calling.

🧰 MCP Tools Reference

🛡️ Fault Tolerance & Error Handling Matrix

🚀 Quick Start

1. Prerequisites

• Python 3.10+ (or uv package manager)

• Telegram API credentials (API_ID and API_HASH) from https://my.telegram.org/apps

2. Installation

# Clone the repository
git clone https://github.com/oladikezz/telegram-user-mcp.git
cd telegram-user-mcp

# Option A: Using uv (Recommended)
uv venv
uv pip install -r requirements.txt

# Option B: Using standard venv + pip
python -m venv .venv
.venv\Scripts\activate   # Windows
# source .venv/bin/activate  # macOS / Linux
pip install -r requirements.txt

3. Authenticate & Generate TELEGRAM_SESSION_STRING

Copy .env.example to .env (or let auth.py prompt you interactively):

cp .env.example .env
python auth.py

auth.py will ask for your phone number, the login code sent via Telegram/SMS, and your 2FA cloud password (if enabled), then automatically write TELEGRAM_SESSION_STRING to .env.

⚙️ MCP Client Configuration

Add the server to your claude_desktop_config.json (Claude Desktop) or .cursor/mcp.json (Cursor IDE):

Option A: Launch via uv (Recommended)

{
  "mcpServers": {
    "telegram-user": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:/Users/user/Desktop/telegram-user-mcp",
        "--with",
        "mcp[cli]",
        "--with",
        "telethon",
        "--with",
        "python-dotenv",
        "python",
        "server.py"
      ],
      "env": {
        "TELEGRAM_API_ID": "12345678",
        "TELEGRAM_API_HASH": "your_api_hash_here",
        "TELEGRAM_SESSION_STRING": "your_session_string_from_auth_py"
      }
    }
  }
}

Option B: Launch via Direct Virtual Environment Python

{
  "mcpServers": {
    "telegram-user": {
      "command": "C:/Users/user/Desktop/telegram-user-mcp/.venv/Scripts/python.exe",
      "args": [
        "C:/Users/user/Desktop/telegram-user-mcp/server.py"
      ]
    }
  }
}

📁 Project Structure

telegram-user-mcp/
├── auth.py                      # Interactive CLI wizard for 2FA auth & StringSession generation
├── server.py                    # FastMCP stdio server with 7 Telethon userbot tools
├── requirements.txt             # Python dependencies (mcp[cli], telethon, python-dotenv, cryptg)
├── claude_desktop_config.json   # Ready-to-use configuration template for Claude / Cursor
├── .env.example                 # Environment variables template
├── .gitignore                   # Protects .env and *.session files from Git tracking
├── README.md                    # Documentation (English)
├── README.ru.md                 # Documentation (Russian)
└── README.zh-CN.md              # Documentation (Chinese)

🇷🇺 Русский

Полная документация на русском языке доступна в README.ru.md.

Telegram User MCP — это готовый к продакшену асинхронный MCP-сервер на Python (FastMCP + Telethon), предоставляющий ИИ-ассистентам (Claude Desktop, Cursor, Goose) прямой доступ к личному аккаунту Telegram по протоколу MTProto.

Основные возможности:

• Полный набор из 7 инструментов: list_dialogs, get_chat_history, search_messages, send_message, edit_message, mark_as_read, get_user_info.

• Одноразовый CLI-авторизатор (auth.py): поддержка кода подтверждения, облачного пароля 2FA и автосохранения TELEGRAM_SESSION_STRING в .env.

• Устойчивость к сбоям: автоматический прогрев кэша диалогов для StringSession, авто-ожидание коротких FloodWaitError и строгая изоляция логов в stderr.

🇨🇳 中文

完整中文文档请参阅 README.zh-CN.md。

Telegram User MCP 是一个基于 Python（FastMCP 与 Telethon）构建的生产级 Model Context Protocol (MCP) 服务器，允许 AI 助手（Claude Desktop、Cursor、Goose）通过原生 MTProto 协议安全地控制您的个人 Telegram 账号（Userbot）。