Fast MCP Telegram

🚀 Fast MCP Telegram Server

Fast MCP Telegram Server は、包括的な検索、メッセージング、および直接的なAPIアクセス機能を備えた、AIアシスタント用の本番環境対応のTelegram統合サービスです。

🌐 デモ

1. https://tg-mcp.redevest.ru/setup を開き、認証フローを開始します。
2. 完了すると、Bearerトークン付きのすぐに使える mcp.json が提供されます。
3. この設定ファイルをMCPクライアントと共に使用して、このMCPサーバーの機能を確認します。
4. または、curlを使用してすぐにHTTP‑MTProtoブリッジを試すことができます（TOKENを置き換えてください）。

curl -X POST "https://tg-mcp.redevest.ru/mtproto-api/messages.SendMessage" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"params": {"peer": "me", "message": "Hello from Demo!"}}'

📖 目次

• ✨ 主な機能
• 🚀 クイックスタート
• 🏗️ サーバーモード
• 🌐 HTTP-MTProtoブリッジ
• 📚 ドキュメント
• 🔒 セキュリティ
• 🤝 コントリビューション
• 📄 ライセンス

✨ 主な機能

🛠️ 利用可能なツール

📖 詳細なツールのドキュメントと例については、ツールリファレンス を参照してください。

🚀 クイックスタート

1. PyPIからインストール

pip install fast-mcp-telegram

2. Telegramで認証

fast-mcp-telegram-setup --api-id="your_api_id" --api-hash="your_api_hash" --phone-number="+123456789"

🌐 ブラウザをお使いの場合：サーバーを起動し、/setup を開いて認証し、すぐに使える mcp.json をダウンロードします。既存のセッションを同じインターフェイスで再認証することもできます。

3. MCPクライアントを設定

STDIOモード（Cursor IDEでの開発）：

{
  "mcpServers": {
    "telegram": {
      "command": "fast-mcp-telegram",
      "env": {
        "API_ID": "your_api_id",
        "API_HASH": "your_api_hash",
        "PHONE_NUMBER": "+123456789"
      }
    }
  }
}

HTTP_AUTHモード（Bearerトークンを使用した本番環境のデプロイメント）：

{
  "mcpServers": {
    "telegram": {
      "url": "https://your-server.com",
      "headers": {
        "Authorization": "Bearer AbCdEfGh123456789KLmnOpQr..."
      }
    }
  }
}

4. 使用を開始！

{"tool": "search_messages_globally", "params": {"query": "hello", "limit": 5}}
{"tool": "send_message", "params": {"chat_id": "me", "message": "Hello from AI!"}}

📝 詳細なインストール手順については、インストールガイド を参照してください。

🏗️ サーバーモード

🌐 HTTP-MTProtoブリッジ

任意のTelegram APIメソッドへの直接的なcurlアクセス - 自動エンティティ解決と安全対策を備えたHTTPリクエストを介して、任意のTelegram MTProtoメソッドを実行します。

クイック例

# 自動エンティティ解決を使用してメッセージを送信
curl -X POST "https://your-domain.com/mtproto-api/messages.SendMessage" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "params": {"peer": "@username", "message": "Hello from curl!"},
        "resolve": true
      }'

# params_jsonを使用してメッセージを送信（n8nなどのツールで動作）
curl -X POST "https://your-domain.com/mtproto-api/messages.SendMessage" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "params_json": "{\"peer\": \"@username\", \"message\": \"Hello from curl!\"}",
        "resolve": true
      }'

# ピア解決を使用してメッセージ履歴を取得
curl -X POST "https://your-domain.com/mtproto-api/messages.getHistory" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "params": {"peer": "me", "limit": 10},
        "resolve": true
      }'

📖 完全なMTProtoブリッジのドキュメントについては、MTProtoブリッジガイド を参照してください。

📚 ドキュメント

• インストールガイド - 詳細なインストールと設定
• デプロイメントガイド - Dockerデプロイメントと本番環境のセットアップ
• ツールリファレンス - 例付きの完全なツールドキュメント
• 検索ガイドライン - 検索のベストプラクティスと制限事項
• 運用ガイド - ヘルスモニタリングとトラブルシューティング
• プロジェクト構造 - コードの組織とアーキテクチャ
• コントリビューションガイド - 開発セットアップとコントリビューションガイドライン

🔒 セキュリティ

主要なセキュリティ機能：

• セッション分離を備えたBearerトークン認証
• ファイルダウンロードのSSRF保護
• オプトインオーバーライドを備えた危険なメソッドのブロッキング
• セッションファイルのセキュリティと自動クリーンアップ

📖 完全なセキュリティ情報については、SECURITY.md を参照してください。

🤝 コントリビューション

コントリビューションを歓迎します！以下の内容については、コントリビューションガイド を参照してください。

• 開発セットアップ手順
• テストガイドライン
• コード品質標準
• プルリクエストプロセス

コントリビューターのクイックスタート：

1. リポジトリをフォークします。
2. コントリビューションガイド を読みます。
3. フィーチャーブランチを作成します。
4. 変更を加え、テストを追加します。
5. プルリクエストを送信します。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています - 詳細については、LICENSE ファイルを参照してください。

🙏 謝辞

• FastMCP - MCPサーバーフレームワーク
• Telethon - Telegram APIライブラリ
• Model Context Protocol - プロトコル仕様

mcp-name: io.github.leshchenko1979/fast-mcp-telegram