mcpField
T
Telegram Bot MCP Server

Telegram Bot MCP Server

ローカル
github.com/cyuanxvコミュニケーション14 日前に更新
リポジトリ

Telegram Bot MCP Server について

リッチテキスト、メディア、インタラクティブボタンで Telegram Bot を操作するセルフホスト型 Node.js サーバーです。Bot の認証情報と実行環境を自分で設定する運用者向けで、高度な機能には個別の権限設定とストレージが必要です。

主な機能

  1. 01リッチテキストメッセージ
  2. 02メディア操作
  3. 03インタラクティブボタン
  4. 04オプションのキューと受信箱
  5. 05Webhook 対応
  6. 06Rich Messages とセッション

活用シーン

  1. 01書式付き Bot メッセージの送信
  2. 02Bot メディアの処理
  3. 03インタラクティブなメッセージボタンの提供
  4. 04設定済み webhook イベントの受信

MCP 対応

Streamable HTTP の `/api/mcp` を通じて、MCP クライアントに Telegram Bot 操作を公開します。デフォルトではローカルループバックにバインドし、実際の Bot 操作には運用者自身の Telegram 認証情報が必要です。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定
{
  "mcpServers": {
    "cyuanxv-telegram-bot": {
      "command": "npx",
      "args": [
        "-y",
        "@cyuanxv/telegram-bot-mcp-server"
      ],
      "env": {
        "MCP_API_KEY": "<MCP_API_KEY>",
        "TELEGRAM_BOT_TOKEN": "<TELEGRAM_BOT_TOKEN>",
        "TELEGRAM_CHAT_ID": "<TELEGRAM_CHAT_ID>"
      }
    }
  }
}
起動コマンドnpx -y @cyuanxv/telegram-bot-mcp-server
設定が必要な環境変数
MCP_API_KEYシークレットChoose a strong local MCP access key. Use the same key in the Authorization header.
TELEGRAM_BOT_TOKENシークレットYour own Telegram Bot token. Required for real Bot operations.
TELEGRAM_CHAT_IDシークレットYour own default Telegram chat ID.

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ
npm@cyuanxv/telegram-bot-mcp-server1.0.1

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

Telegram Bot MCP サーバー

リッチテキスト、メディア、インタラクティブボタンに対応したセルフホスト可能な Telegram Bot MCP サーバーです。Node.js 24 が必要です。このソースパッケージは Streamable HTTP を使用し、127.0.0.1 にバインドします。stdio サーバーではなく、ホステッドサービスも含まれていません。

インストール

提供されたソース .tgz を、ライフサイクルスクリプトを実行せずに専用ディレクトリへインストールします。

npm install --ignore-scripts /absolute/path/to/cyuanxv-telegram-bot-mcp-server-1.0.0.tgz

一般公開後は、同じバージョンを npx --yes @cyuanxv/[email protected] --port 3000 で起動することもできます。このパブリックパッケージ用コマンドは、そのバージョンが公開された後にのみ使用でき、以下に記載するサービス環境が必要です。

サービス環境で強力な MCP_API_KEY を設定し、./node_modules/.bin/telegram-bot-mcp-server --port 3000 を実行します。初回起動時にソースがローカルでビルドされ、以降の起動ではそのビルドが使用されます。再ビルドするには build サブコマンドを使用し、既存のビルドを必須にするには start を使用します。ソースのビルド用ワークスペースは ~/.cache/telegram-bot-mcp-server/ にあります。このユーザーキャッシュを書き込み可能な状態に保ってください。依存関係は npm のインストール先に残ります。インストールフックがサービスをビルドまたは起動することはありません。

Authorization: Bearer <your MCP_API_KEY> を使用して http://127.0.0.1:3000/api/mcp に接続します。実際の Bot 操作には、独自の TELEGRAM_BOT_TOKEN と TELEGRAM_CHAT_ID を指定してください。トークンをコマンドライン引数に含めないでください。別のマシンにデプロイする場合は、独自の認証済み HTTPS リバースプロキシを設定してください。クラウドクライアントは、ローカルのループバックアドレスに直接接続できません。

デフォルトでは、キュー、受信トレイ、メディアバイトのアップロード、コールバック、Rich Messages、個人アカウントなどの高度な機能は自動的に有効になりません。有効にする前に、対応する権限、対象範囲、ストレージを設定してください。migrations/ には機能ごとにグループ化された SQL が含まれています。runtime の権限付与の例は別途確認してください。マイグレーション管理者の認証情報を実行サービスに渡さないでください。

webhook の所有権確認と登録に使用するため、TELEGRAM_PUBLIC_ORIGIN には独自の HTTPS サービスのルートアドレスを設定する必要があります。設定しない場合は .invalid のプレースホルダーアドレスとなり、実際のイベントを受信できません。

demo-group は、プライベート設定を置き換えるための互換エイリアスであり、実在するグループではありません。基本のデフォルトチャットはこのエイリアスにマッピングされます。現在、直接の Rich 送信は default Bot／demo-group のみが利用でき、プライベートチャットには Rich session と明示的な対象の権限付与が必要です。webhook の自動登録、アカウントのインポート、メッセージの送信は行われません。

MCP キーは、raw chat ID を受け付けるツールを含む、信頼されたオペレーターアクセスを許可します。設定済みのエイリアスは、受信者の許可リストではありません。依存関係にはそれぞれ独自のライセンスが適用されます。THIRD_PARTY_NOTICES.md を参照してください。このプロジェクトは Telegram と提携していません。

作者と著作権

© 2026 cyuanxv · X / Twitter @cyuanxv

独自のソースコードは MIT ライセンスの下で提供されています。

コメント

Markdown 対応

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。