Telegram MCP Server

Gemini Spark や Claude Desktop などの MCP（Model Context Protocol）クライアントから、Telegram メッセージの送受信を行えるようにするための MCP サーバーです。

---

前提条件

動作には Node.js が必要です。

1. Node.js のインストール:

   • まだインストールされていない場合は、Node.js 公式サイト から LTS 版をダウンロードしてインストールしてください。
   • インストール完了後、コマンドプロンプトや PowerShell を再起動し、node -v および npm -v が動作することを確認してください。

2. Telegram Bot の作成:

   • Telegram アプリ内で @BotFather を検索し、/newbot コマンドを使用して新しい Bot を作成します。
   • 作成後に表示される HTTP API Token（例: 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ）を控えておきます。

---

セットアップ手順

1. リポジトリディレクトリに移動し、依存関係をインストールします:

   npm install
   

2. 環境変数の設定:

   • ディレクトリ内の .env.example を .env にコピーします。

   copy .env.example .env
   

   • .env ファイルを開き、控えておいた TELEGRAM_BOT_TOKEN を設定します。

   TELEGRAM_BOT_TOKEN=ここにBotのトークンを貼り付け
   TELEGRAM_DEFAULT_CHAT_ID=（任意）デフォルトの宛先チャットID
   

   ※ TELEGRAM_DEFAULT_CHAT_ID を指定しておくと、ツール呼び出し時にチャットIDを省略した場合に自動的にそのチャットに送信されます。

3. ビルドの実行: TypeScript を JavaScript にコンパイルします。

   npm run build
   

---

サーバーの起動とMCPクライアントへの登録方法

1. サーバーの起動

ローカルで起動する場合は、依存関係をインストール、ビルドした後に以下のように起動します。

npm start

デフォルトではポート 3000 でサーバーが起動し、以下のエンドポイントが利用可能になります。

• SSEエンドポイント: http://localhost:3000/sse

ポート番号を変更したい場合は、環境変数 PORT を指定して起動するか、.env ファイルに PORT=8080 のように追記してください。

2. MCP クライアントへの登録

Claude Desktop の場合

設定ファイル（例: AppData\Roaming\Claude\claude_desktop_config.json）に以下のように SSE サーバーを追加します。

{
  "mcpServers": {
    "telegram-mcp": {
      "type": "sse",
      "url": "http://localhost:3000/sse"
    }
  }
}

Gemini Spark 等のクライアントの場合

クライアントの設定画面で SSE トランスポートを選択し、URL に http://localhost:3000/sse を指定して登録します。

---

提供ツール

1. telegram_get_me

• 概要: Bot自身のアカウント情報を取得します。接続確認テストに便利です。
• パラメータ: なし

2. telegram_send_message

• 概要: 指定した chat_id にメッセージを送信します。
• パラメータ:
  • text (string, 必須): 送信するメッセージ。
  • chat_id (string, 任意): 送信先チャットIDまたはユーザー名（例: @my_channel）。指定しない場合は .env のデフォルトIDが使用されます。
  • parse_mode (string, 任意): 書式設定モード（Markdown, HTML, MarkdownV2 から選択）。

3. telegram_get_updates

• 概要: Bot宛ての最新メッセージ（アップデート）を取得します。
• パラメータ:
  • offset (number, 任意): 取得開始位置となるアップデートID。
  • limit (number, 任意): 一度に取得する最大件数（1〜100、デフォルト100）。
  • timeout (number, 任意): ロングポーリングのタイムアウト秒数。