Telegram MCP Server

Локальный сервер Model Context Protocol, который предоставляет ИИ-агенту (Claude Code, Claude Desktop или любому MCP-клиенту) контролируемый доступ к вашему собственному аккаунту Telegram: список чатов, чтение истории, поиск и отправка сообщений через MTProto API Telegram.

Создан на Python + Telethon. Полностью работает на вашем компьютере; ваша сессия входа никогда его не покидает.

Why

Telegram Bot API не может видеть ваши существующие чаты; бот — это отдельная личность и получает только сообщения, явно отправленные ему. Чтобы агент мог работать с вашими реальными разговорами, вам нужен MTProto client API, аутентифицированный как ваша учётная запись. Этот проект оборачивает это в небольшой специализированный MCP-сервер, чтобы любой MCP-совместимый агент мог читать и действовать в вашем Telegram; без необходимости каждый раз писать связующий код.

Related MCP server: telegram-mcp

How it fits together

Telegram бот — это отдельная личность и видит только сообщения, отправленные ему. Чтобы агент мог работать с вашими разговорами, сервер аутентифицируется как ваша учётная запись через MTProto, вот почему строка сессии так важна.

flowchart LR
    AGENT["<b>MCP client</b><br/>Claude Code · Claude Desktop<br/>or any MCP-capable agent"]

    subgraph LOCAL ["Your machine — nothing leaves it but Telegram traffic"]
        direction TB
        SRV["<b>server.py</b> · FastMCP stdio server<br/>connects lazily on first tool call<br/>verifies the session is authorized"]
        TOOLS["<b>6 tools</b><br/>get_me · list_chats · get_history<br/>search_messages · search_all · send_message"]
        ENV[("<b>.env</b> · git-ignored<br/>api_id · api_hash<br/><b>SESSION_STRING</b><br/><i>equivalent to being logged in as you</i>")]
        LOGIN["<b>login.py</b> · run once<br/>phone + code + 2FA → StringSession"]
        SRV --> TOOLS
        LOGIN -->|"writes"| ENV
        ENV -->|"reads"| SRV
    end

    subgraph TL ["Telethon → MTProto"]
        direction TB
        M1["iter_dialogs"]
        M2["iter_messages"]
        M3["SearchGlobalRequest"]
        M4["send_message"]
    end

    TG[("<b>Telegram</b><br/>your real account,<br/>your existing chats")]
    BOT(["Bot API<br/><i>cannot see your chats —<br/>this is why MTProto</i>"])

    AGENT <-->|"MCP over stdio"| SRV
    TOOLS --> M1
    TOOLS --> M2
    TOOLS --> M3
    TOOLS --> M4
    TL <--> TG
    BOT -.->|"✗"| TG

    classDef secret fill:#7f1d1d,stroke:#f87171,stroke-width:2px,color:#fee2e2
    classDef no fill:#0f172a,stroke:#475569,stroke-width:1.5px,color:#94a3b8
    classDef core fill:#312e81,stroke:#818cf8,stroke-width:2px,color:#e2e8f0
    class ENV secret
    class BOT no
    class SRV,TOOLS core

Результаты возвращаются в виде простых JSON-сериализуемых словарей, поэтому агент обобщает структурированные данные, а не извлечённый текст.

Features

• 6 инструментов, покрывающих основные операции чтения/записи (см. ниже)

• Только локально — учётные данные и сессия хранятся в git-ignored .env; ничего не отправляется никуда, кроме Telegram

• Стандартный MCP stdio-сервер — работает с Claude Code, Claude Desktop или любым MCP-клиентом

• Одноразовый вход — интерактивный скрипт сохраняет переиспользуемую строку сессии; не нужно повторно аутентифицироваться при каждом запуске

• Маленький и читаемый — ~150 строк Python, легко проверять и расширять

Tools

chat принимает имя пользователя (@name), числовой id, номер телефона, ссылку t.me или отображаемое имя чата.

Quickstart

1. Install

git clone https://github.com/<you>/telegram-mcp.git
cd telegram-mcp
python -m venv .venv

# Windows
.venv\Scripts\pip install -r requirements.txt
# macOS / Linux
.venv/bin/pip install -r requirements.txt

2. Get API credentials

Перейдите на my.telegram.org → API development tools → создайте приложение → скопируйте api_id и api_hash.

3. Log in (one time)

# Windows
.venv\Scripts\python login.py
# macOS / Linux
.venv/bin/python login.py

Введите ваш api_id/api_hash, номер телефона (с кодом страны) и код входа, который Telegram отправит вам (плюс пароль 2FA, если он установлен). Это записывает переиспользуемую сессию в .env.

4. Register with your MCP client

Claude Code:

claude mcp add telegram --scope user -- "/abs/path/.venv/bin/python" "/abs/path/server.py"

Claude Desktop; добавьте в claude_desktop_config.json:

{
  "mcpServers": {
    "telegram": {
      "command": "/abs/path/.venv/bin/python",
      "args": ["/abs/path/server.py"]
    }
  }
}

Перезапустите клиент, и инструменты telegram станут доступны.

Example

Вы: Найдите во всех моих Telegram-чатах "invoice" и обобщите, что ещё не оплачено.

Агент вызывает search_all("invoice"), который возвращает:

[
  {
    "id": 84213,
    "date": "2026-07-02T09:14:00+00:00",
    "chat": "Acme Billing",
    "from": "Acme Billing",
    "text": "Invoice #204 is due on the 10th."
  }
]

…и агент обобщает на основе этого.

How it works

login.py аутентифицируется один раз через Telethon и сохраняет StringSession в .env. server.py создаёт FastMCP stdio-сервер, подключается лениво при первом вызове инструмента, проверяет, что сессия авторизована, и сопоставляет каждый инструмент с вызовом Telethon (iter_dialogs, iter_messages, SearchGlobalRequest, send_message). Результаты возвращаются в виде простых JSON-сериализуемых словарей.

Security

• Храните .env в тайне. SESSION_STRING эквивалентен входу в систему от вашего имени. Он игнорируется git, никогда не коммитьте его.

• Всё работает локально; сервер общается только с серверами Telegram.

• Автоматизация пользовательского аккаунта — серая зона в условиях использования Telegram. Чтение собственного аккаунта обычно допустимо; поддерживайте человеческий темп отправки и избегайте массовых/спам-действий, чтобы не превысить лимиты аккаунта.

Limitations

• Пока нет автоматического набора тестов; проверено вручную на живом аккаунте.

• search_messages ищет в одном чате; используйте search_all для глобального поиска.

• Разрешение отображаемого имени сводится к сканированию списка диалогов, поэтому точные имена пользователей/идентификаторы быстрее и надёжнее.

License

MIT