Skip to main content
Glama
deenesjakoruzh
Steph-ux

telegram-mcp-server

by Steph-ux
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

telegram-mcp-server

Telethon ベースのTelegram MCPサーバー — 永続クライアント、フラッドセーフ、9つのグループ化されたツール。

コード内にAPIキーは不要。 セッションファイルはローカルに保存。ユーザーアカウント（2FA）とボットの両方に対応。

1. インストール

git clone <this-repo> telegram-mcp-server
cd telegram-mcp-server

python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

pip install -e .

API認証情報を取得

  1. my.telegram.org にアクセス

  2. 電話番号でログイン

  3. アプリを作成 → API ID と API Hash を取得

初回認証

# User account (with 2FA support)
export TG_API_ID=12345
export TG_API_HASH="your_hash_here"
telegram-mcp-server --auth --phone +33612345678

# Or via MCP tool: tg_session(action="auth", api_id=12345, api_hash="...", phone="+33612345678")

Related MCP server: telegram-mcp

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

Claude Desktop / OpenCode

{
  "mcpServers": {
    "telegram": {
      "command": "telegram-mcp-server",
      "env": {
        "TG_API_ID": "12345",
        "TG_API_HASH": "your_hash_here"
      }
    }
  }
}

PATHにない場合:

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "telegram_mcp_server"],
      "env": {
        "TG_API_ID": "12345",
        "TG_API_HASH": "your_hash_here"
      }
    }
  }
}

Docker

docker build -t telegram-mcp .
docker run -i --rm \
  -v ~/.telegram-mcp/sessions:/root/.telegram-mcp/sessions \
  -e TG_API_ID=12345 \
  -e TG_API_HASH="your_hash" \
  telegram-mcp

3. ツールカタログ（9ツール、8アクション）

tg_session — セッション管理

action

必須引数

説明

auth

api_id, api_hash, phone または bot_token

認証（2FA対応）

check

—

ログイン状態を確認

logout

—

セッションを削除

tg_message — 送信、転送、削除、返信

action

必須引数

説明

send

target, text

メッセージを送信

forward

target, message_id, to_target

メッセージを転送

delete

target, message_id

メッセージを削除

reply

target, message_id, text

メッセージに返信

tg_chat — チャット操作

action

必須引数

説明

list

—

最近のチャットを一覧

info

target

チャット情報を取得

members

target

チャットメンバーを一覧

leave

target

チャットから退出

tg_search — 検索

action

必須引数

説明

messages

query

メッセージを検索（target 内で任意）

users

query

連絡先・ユーザーを検索

channels

query

チャンネルを検索

tg_history — チャット履歴

action

必須引数

説明

messages

target

メッセージ履歴を取得

media

target

メディアのみの履歴を取得

files

target

ファイルのみの履歴を取得

tg_user — ユーザー操作

action

必須引数

説明

me

—

自分の情報を取得

info

target

ユーザー情報を取得

block

target

ユーザーをブロック

unblock

target

ユーザーのブロックを解除

tg_media — メディア送信

action

必須引数

説明

send_photo

target, file_path

写真を送信

send_video

target, file_path

動画を送信

send_file

target, file_path

ドキュメントを送信

send_voice

target, file_path

音声メモを送信

tg_channel — チャンネル管理

action

必須引数

説明

create

title

スーパーグループ/チャンネルを作成

join

target

チャンネルに参加

leave

target

チャンネルから退出

info

target

チャンネル情報を取得

tg_draft — 下書きメッセージ

action

必須引数

説明

save

target, text

下書きを保存

list

—

すべての下書きを一覧

delete

target

下書きを削除

4. 環境変数

変数

デフォルト

説明

TG_API_ID

0

Telegram API ID（my.telegram.org から）

TG_API_HASH

""

Telegram API Hash

TG_SESSION_DIR

~/.telegram-mcp/sessions

セッションファイルの保存場所

5. 安全性

  • レートリミッター: 送信アクションは毎分5回まで。読み取りアクションは無制限。

  • FloodWaitError 自動リトライ: 必要な時間だけ待機（最大5分）。

  • セッションファイル: ローカルのみに保存され、git にコミットされることはありません。

  • 2FA対応: 二段階認証が有効なアカウントを完全サポート。

6. MCPリソース

  • tg://version — サーバーバージョン

  • tg://session/status — ログイン状態

ライセンス

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

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • 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

    chenzhaoxuan0
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables interaction with Telegram Bot API for sending messages, photos, editing messages, answering callbacks, and fetching updates.
    MIT

  • telegram-mcp

    Shaan-alpha
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to interact with a user's Telegram account: list chats, read history, search, and send messages through Telegram's MTProto API.
    1
    MIT