telegram-bot-mcp

ClaudeがTelegram Bot APIを通じてTelegramチャンネルを管理できるようにするMCPサーバー — 日次の購読者数の増加を追跡し、投稿の公開・編集・ピン留め・削除ができます。

🇮🇷 راهنمای فارسی · デプロイガイド · راهنمای دپلوی

これは何か

TelegramのBot APIは単純なHTTPS APIです。このリポジトリはそれをModel Context Protocolでラップし、AIアシスタントがツールとして呼び出せるようにします — 「今週のチャンネルの調子はどう？」という問いを、curl https://api.telegram.org/bot.../getChatMemberCount の代わりに実現します。

同じツール定義から、2つの形態で提供されます：

毎日のレポートを手間なく実行したい場合はリモートサーバーを、Claude Codeのみを使用していてマシンから情報を出したくない場合はプラグインを選んでください。

ツール

どちらのビルドも同じ8つのツールを公開します。

クイックスタート（リモートサーバー）

1. @BotFather でボットを作成 → /newbot → トークンをコピー。

2. ボットをチャンネルの管理者として追加。

3. val.town でHTTP valを作成し、remote/telegram-mcp.ts を貼り付け。

4. valのサイドバーで3つの環境変数を設定： TELEGRAM_BOT_TOKEN、TELEGRAM_CHANNEL、MCP_PASSWORD。

5. Claudeで：設定 → コネクタ → カスタムコネクタを追加 → https://<your-val>.web.val.run/mcp → パスワードを入力。

完全なチュートリアル（ローカルプラグインとトラブルシューティングを含む）は docs/deployment.md を参照してください。

セキュリティ

このリポジトリには資格情報は一切コミットされていません。 config.json と .env はgitignoreされており、.example ファイルのみが追跡されています。フォークをプッシュする前に、git status で秘密情報が含まれていないことを必ず確認してください。

リモートサーバーは、インターネット上に公開されたままではなく、完全なOAuth 2.1認可フローを実装しています：

• 有効なbearerトークンがないリクエストには、RFC 7591 に従って WWW-Authenticate ヘッダー付きの 401 を返します。

• クライアントは動的に登録され（RFC 7591）、クライアントシークレットは不要。

• 認可コードはPKCE（S256）で保護され、リダイレクトURIは検証されます。

• アクセストークンとリフレッシュトークンはHMAC-SHA256で署名され、ステートレス — 24時間のアクセストークンと30日間のリフレッシュトークン。

• 同意画面は MCP_PASSWORD で保護されており、これは自分で選択します。

ボットトークンはサーバー環境変数にのみ存在し、どのツールからも返されません。

制限事項

購読者数のみが取得可能です。投稿のビュー数、転送数、リーチ、Telegram公式のチャンネル統計グラフはボットには公開されていません。これらは、チャンネルにログインしたユーザーアカウントを持つMTProtoクライアントが必要です。

ボットは通常、自分が送信したメッセージのみ編集できます。can_edit_messages 管理者権限（「他のユーザーのメッセージを編集（チャンネルのみ）」）はありますが、人間の管理者による投稿に対するボットの動作は明確に文書化されていません — 実際に自分のチャンネルでテストしてから依存してください。削除は異なります： can_delete_messages は他のユーザーのメッセージを明示的にカバーしています。

成長の追跡には、実行間で履歴ストアが永続化されている必要があります。Val Townではブロブストレージがそれを行います。ローカルプラグインではCSVファイルです — 一時ディレクトリではなく、永続的な場所に置いてください。

リポジトリ構成

remote/telegram-mcp.ts              Remote MCP server (Val Town HTTP val, Deno)
plugin/                             Claude Code plugin
  .claude-plugin/plugin.json          Plugin manifest
  .mcp.json                           stdio MCP server registration
  server/telegram_mcp_server.py        MCP server (Python 3, stdlib only)
  skills/telegram-channel-report/      Skill that turns tools into a readable report
  config.example.json                  Template — copy to config.json
tests/                              Test suite for the remote server
docs/                               Deployment guides (English / فارسی)

テスト

npm test

Node 22.6+ が必要です。OAuthフロー（401チャレンジ、動的クライアント登録、PKCE拒否、トークンおよびリフレッシュ付与、偽造トークン拒否）とMCPプロトコル（initialize、通知、ツール一覧、ツール呼び出し）をカバーする22のチェックがあります。Telegram APIはモック化されており、実際のネットワークアクセスやボットトークンは必要ありません。

スイートはデプロイされたソースに対して実行され、remote/ と plugin/ の両ツール定義が同期していることを確認します。

ライセンス

MIT