Skip to main content
Glama
Sign In
deenesjakoruzh
telegram-mcp

telegram-mcp

by Shaan-alpha
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Telegram MCP Server

A local Model Context Protocol server that gives an AI agent (Claude Code, Claude Desktop, or any MCP client) controlled access to your own Telegram account: list chats, read history, search, and send messages, through Telegram's MTProto API.

Built with Python + Telethon. Runs entirely on your machine; your login session never leaves it.

Python MCP License

なぜ

TelegramのBot APIは既存のチャットを見ることができません。ボットは別のアイデンティティであり、明示的に送信されたメッセージしか受け取りません。エージェントがあなたの実際の会話を扱うには、MTProtoクライアントAPIをユーザーアカウントとして認証して使う必要があります。このプロジェクトはそれを小さく焦点を絞ったMCPサーバーにラップし、MCP対応のエージェントがあなたのTelegramを読み取って操作できるようにします。毎回グルーコードを書く必要はありません。

Related MCP server: tdlib-mcp-server

仕組み

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シリアライズ可能なdictとして返されるため、エージェントはスクレイピングされたテキストではなく構造化データから要約します。

機能

  • 6つのツールが一般的な読み書き操作をカバー（下記参照）

  • ローカルのみ — 認証情報とセッションはgit無視の.envに保存され、Telegram以外には何も送信されません

  • 標準MCP stdioサーバー — Claude Code、Claude Desktop、または任意のMCPクライアントで動作

  • 一度きりのログイン — 対話型スクリプトが再利用可能なセッション文字列を保存。毎回の再認証は不要

  • 小さく読みやすい — Python約150行で、監査や拡張が簡単

ツール

Tool

Description

get_me()

接続中のアカウントを返す（動作確認用）

list_chats(limit=20)

最近の会話一覧

get_history(chat, limit=30)

1つのチャットの最近のメッセージ

search_messages(chat, query, limit=30)

1つのチャット内を検索

search_all(query, limit=30)

全チャットを一度に検索

send_message(chat, text)

あなたとしてメッセージを送信

chat はユーザー名（@name）、数値ID、電話番号、t.meリンク、またはチャットの表示名を受け付けます。

クイックスタート

1. インストール

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. API認証情報を取得

my.telegram.org → API development tools → アプリを作成 → api_id と api_hash をコピーします。

3. ログイン（一度きり）

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

api_id/api_hash、電話番号（国番号付き）、Telegramから送信されるログインコード（設定している場合は2FAパスワードも）を入力します。これにより再利用可能なセッションが.envに書き込まれます。

4. MCPクライアントに登録

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ツールが利用可能になります。

例

あなた： すべての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."
  }
]

…そしてエージェントはそこから要約します。

仕組み

login.pyはTelethonを介して一度認証し、StringSessionを.envに保存します。server.pyはFastMCP stdioサーバーを構築し、最初のツール呼び出しで遅延接続し、セッションが認証されていることを確認し、各ツールをTelethonの呼び出し（iter_dialogs、iter_messages、SearchGlobalRequest、send_message）にマッピングします。結果はプレーンなJSONシリアライズ可能なdictとして返されます。

セキュリティ

  • .envを秘密に保つ。 SESSION_STRINGはあなたとしてログインしているのと同じです。git無視されているので、コミットしないでください。

  • すべてローカルで実行され、サーバーはTelegramのサーバーとのみ通信します。

  • ユーザーアカウントの自動化はTelegramの利用規約のグレーゾーンです。自分のアカウントを読むことは通常問題ありません。送信は人間のペースに保ち、一括送信やスパム行為を避けてアカウント制限にかからないようにしてください。

制限事項

  • 自動テストスイートはまだありません。実アカウントで手動検証済みです。

  • search_messagesは単一のチャットを検索します。全体検索にはsearch_allを使用してください。

  • 表示名の解決はダイアログリストのスキャンにフォールバックするため、正確なユーザー名/IDの方が高速で信頼性が高いです。

ライセンス

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Resources

Related MCP Connectors

Related MCP Servers

  • telegram-mcp

    VovaVindar
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to read, send, and organize Telegram messages and chats. Supports tools for listing chats, fetching messages, sending/reply, archiving, muting, and folder management.
    1
    MIT

  • tdlib-mcp-server

    Crocodile-beep
    F
    license
    Not graded
    quality
    D
    maintenance
    Connects AI agents to Telegram via the official TDLib library, enabling tools like getting user info, listing dialogs, and searching messages.
    -

  • telegram-mcp

    naim30
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to control a real Telegram user account via MTProto, allowing message sending, chat reading/searching, and message management through MCP tools.
    30 npm
    -

  • Telegram MCP Server

    Muhammadyunusxon
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI assistants to control a personal Telegram account for sending/reading messages, media, group management, and more via the MTProto API.
    MIT

Appeared in Searches