MCP Telegram

mcp-telegram

Claude、Codex、Cursor、Claude Code、VS Code、Cline、Windsurf などの MCP クライアント向けの Telegram MCP サーバーです。MTProto 経由の実際の Telegram ユーザーアカウント、ブラウザベースのローカルサインイン、100 以上のツールを備えています。遅延読み込みとコンテキストコストの削減が必要ですか？ スキルベースのコンパニオンである telegram-agent をご覧ください。

Model Context Protocol（MCP）サーバーです。Claude Desktop、Codex CLI、Cursor、Claude Code、VS Code、Cline、Windsurf、Goose、その他の MCP 互換クライアントを、MTProto 経由で実際の Telegram ユーザーアカウントに接続します。これにより、Telegram の UI をクリックして操作する代わりに、エージェントがチャットや自動化されたツール呼び出しから Telegram のチャットを読み取り、検索し、送信し、モデレートし、管理できるようになります。

用途: ダイアログの読み取りとメッセージのグローバル検索 · 送信/編集/転送/リアクション/投票 · メディアのダウンロードとボイスメモの文字起こし · チャンネルのモデレーション（BAN/制限/昇格、招待リンク、スローモード、管理ログ、フォーラムトピック） · ストーリー、連絡先、下書き、通知、フォルダ、プライバシーの管理 · その他なんでも生の MTProto ブリッジにフォールスルー。すべて単一のサインイン済みユーザーアカウントに対して実行され、ボットは不要です。

警告

このサーバーは（ボットではなく）実際の Telegram ユーザーとしてサインインします。セッションは ~/.telegram-agent/ に保存されます。このディレクトリはパスワードと同様に扱ってください。

前提条件

1. Node.js >=20
2. my.telegram.org/apps で取得した Telegram API 認証情報 — api_id と api_hash

より軽量なトランスポートをお探しですか？

このパッケージは MCP サーバーです — すべてのツールスキーマ（約 12,700 トークン）が、毎ターン、エージェントのコンテキストに常駐します。どの MCP クライアントにも、またシェル呼び出しができないホスト型ランタイムにも適しています。

お使いのエージェントが Claude Code / Codex CLI / Cursor / Gemini CLI / Cline / Windsurf であれば、同じ Telegram の機能面をユニバーサルエージェントスキルとして提供するコンパニオンパッケージ — telegram-agentがあります。エージェントは、プロンプトに Telegram が含まれる場合にのみスキルの手順を読み込むため、アイドル時のコンテキストコストが約 50 分の 1 になります。スタンドアロン（MCP サーバーを介在させません）ですが、このパッケージと同じ ~/.telegram-agent/ セッションストアを使用します — 一度サインインすれば、どちらか一方または両方を使えます。

npm i -g telegram-agent
telegram-agent login
npx skills add beautyfree/telegram-agent -a claude-code -g

MCP のインストール手順については以下に続きます。

インストール

オプション A — 自動、すべてのクライアント:

npx add-mcp mcp-telegram \
  --env TELEGRAM_API_ID=123456 \
  --env TELEGRAM_API_HASH=abc...

add-mcp（Neon 製）は、Claude Desktop、Claude Code、Cursor、VS Code、Codex、Gemini CLI、Cline、Zed、Goose、OpenCode などに適切な設定を書き込みます。対話式プロンプトでクライアントを選択してください。

重要

両方の環境変数が必須です。my.telegram.org/apps で取得してください。

オプション B — 手動設定:

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "mcp-telegram"],
      "env": {
        "TELEGRAM_API_ID": "123456",
        "TELEGRAM_API_HASH": "abc..."
      }
    }
  }
}

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "mcp-telegram"],
      "env": {
        "TELEGRAM_API_ID": "123456",
        "TELEGRAM_API_HASH": "abc..."
      }
    }
  }
}

{
  "servers": {
    "telegram": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-telegram"],
      "env": {
        "TELEGRAM_API_ID": "123456",
        "TELEGRAM_API_HASH": "abc..."
      }
    }
  }
}

claude mcp add telegram \
  -e TELEGRAM_API_ID=123456 \
  -e TELEGRAM_API_HASH=abc... \
  -- npx -y mcp-telegram

[mcp_servers.telegram]
command = "npx"
args = ["-y", "mcp-telegram"]
env = { TELEGRAM_API_ID = "123456", TELEGRAM_API_HASH = "abc..." }

エージェントに次のように依頼します。

私の Telegram にサインインして。

エージェントが login ツールを呼び出します。ブラウザのタブが開きます。電話番号、SMS コード、そして 2 段階認証を設定している場合はそのパスワードを入力してください。タブに緑色のチェックマークが表示されたら、閉じてかまいません。これでセッションがローカルに保存され、エージェントがあなたの Telegram を読めるようになります。

別のアカウントを追加するには、エージェントに再度 login を呼び出すよう依頼してください。

ツール

Telegram のユーザーアカウント機能の全体をカバーする 102 個のツールです。よく使うものは以下に示し、残りは折りたたみ内にグループ分けしています。すべてのツールは省略可能な accountId を受け付けます（サインインしているアカウントが 1 つだけの場合は省略してください）。peer は数値のチャット id、@username、またはリテラルの "me"（Saved Messages）を受け付けます。

メニューのトップ:

公開するツールの制御

3 つの環境変数を、順番に適用します。

例:

MCP_TELEGRAM_READONLY=1                                    # read-only agent
MCP_TELEGRAM_TOOLS='login,list*,search*,get*'              # discovery-only
MCP_TELEGRAM_DISABLE='delete*,ban*,kick*,create_channel,delete_channel,transfer_ownership,invokeMtproto'  # safer write set

環境

エージェントが参照するツールの選択

3 つのゲート変数は積み重なります — MCP_TELEGRAM_READONLY → MCP_TELEGRAM_TOOLS → MCP_TELEGRAM_DISABLE。

# Read-only agent — every mutating tool is hidden
MCP_TELEGRAM_READONLY=1

# Discovery-only — only login + the list/search/get tools
MCP_TELEGRAM_TOOLS='login,list*,search*,get*,resolveUsername'

# Allow writes but keep destructive ones away from the agent
MCP_TELEGRAM_DISABLE='delete*,ban*,kick*,create_channel,delete_channel,transfer_ownership,invokeMtproto'

# Specific surface: read + send/edit only
MCP_TELEGRAM_TOOLS='login,list_accounts,list_dialogs,list_messages,search_messages,search_global,send_message,editMessage'

MCP クライアントの設定では、これらを TELEGRAM_API_ID/TELEGRAM_API_HASH と同じ env ブロックに記述します。確認するには、クライアントを開き直してください — サーバーが公開するツールは、ゲートの実行後に登録されたものとまったく同じです。

データレイアウト

~/.telegram-agent/
├── state.json          known accounts (no secrets in here)
└── sessions/
    └── <account_id>/   per-account MTProto session

Telegram セッションがサーバー側で無効化された場合（別のデバイスからのログアウト、パスワードの変更など）、次回のツール呼び出しでエラーが返され、エージェントに再認証のため login を呼び出すよう通知します。

開発

git clone https://github.com/beautyfree/mcp-telegram
cd mcp-telegram
npm install
echo "TELEGRAM_API_ID=...\nTELEGRAM_API_HASH=..." > .env
npm run dev

レイアウト:

src/
├── index.ts           bin entry — stdio MCP server, tool registrations
├── telegram.ts        MTProto client + login state machine
├── auth-browser.ts    ephemeral HTTP server that drives the browser flow
├── auth-page.ts       inline HTML for the auth page
├── state.ts           persistent state in ~/.telegram-agent/
└── logger.ts

ライセンス

MIT — LICENSE を参照してください。