Telegram MCP Server

🚀 Telegram MCP 服務器

這是一個強大的 MCP（模型上下文協議）服務器，它能讓 Claude 與 Telegram 頻道和群組進行交互。該服務器既支持網頁抓取，也支持通過 API 直接訪問 Telegram 內容。

🚀 特性

0.3.0 版本 - 雙模式運行

API 模式（推薦） ⚡

• 比網頁抓取快 100 倍
• 通過 Telegram 的 MTProto 協議直接訪問
• 支持在頻道內搜索
• 可訪問你所在的私有頻道
• 提供完整的消息元數據（瀏覽量、反應、轉發情況）
• 持久會話 - 只需認證一次
• 無需瀏覽器自動化操作
• 默認情況下可無限檢索帖子

網頁抓取模式 🌐

• 無需 API 憑證
• 使用 Puppeteer 基於瀏覽器進行抓取
• 支持對受限內容進行認證
• 可提取視覺媒體
• 適合快速、匿名訪問

📋 先決條件

• Node.js 18.0.0 或更高版本
• Chrome/Chromium（用於網頁抓取模式）
• Telegram API 憑證（用於 API 模式） - 在此獲取

🛠️ 安裝步驟

1. 克隆此倉庫：

git clone https://github.com/DLHellMe/telegram-mcp-server.git
cd telegram-mcp-server

2. 安裝依賴：

npm install

3. 複製示例環境文件：

cp .env.example .env

4. 編輯 .env 文件並添加配置：

   • 對於 API 模式：添加你的 TELEGRAM_API_ID 和 TELEGRAM_API_HASH
   • 對於網頁抓取模式：默認設置即可使用

5. 構建項目：

npm run build

🔧 配置

獲取 Telegram API 憑證

1. 訪問 https://my.telegram.org
2. 使用你的電話號碼登錄
3. 點擊“API 開發工具”
4. 創建一個新應用
5. 將 api_id 和 api_hash 複製到 .env 文件中

Claude 桌面端配置

將以下內容添加到你的 Claude 桌面端配置文件中：

Windows：%APPDATA%\Claude\claude_desktop_config.json
macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "telegram-scraper": {
      "command": "node",
      "args": ["/absolute/path/to/telegram-mcp-server/dist/index.js"],
      "env": {
        "TELEGRAM_API_ID": "your_api_id",
        "TELEGRAM_API_HASH": "your_api_hash"
      }
    }
  }
}

📖 使用方法

配置完成後，重啟 Claude 桌面端。Telegram 工具將在 Claude 中可用。

API 模式工具

1. telegram_api_login - 與 Telegram 進行認證（僅首次需要）

使用 telegram_api_login 連接到 Telegram

2. api_scrape_channel - 抓取頻道帖子（默認無限制）

使用 api_scrape_channel，參數 url="https://t.me/channelname"

也可以設置限制：

使用 api_scrape_channel，參數 url="https://t.me/channelname" 且 max_posts=50

3. api_search_channel - 在頻道內搜索

使用 api_search_channel，參數 url="https://t.me/channelname" 且 query="keyword"

網頁抓取工具

1. scrape_channel - 抓取公共頻道

使用 scrape_channel，參數 url="https://t.me/channelname"

2. telegram_login - 登錄受限內容

使用 telegram_login，參數 phone="+1234567890"

🔒 數據存儲

會話數據和 cookie 存儲在特定平臺的目錄中：

• Windows：%APPDATA%\telegram-mcp-data
• macOS：~/Library/Application Support/telegram-mcp-data
• Linux：~/.config/telegram-mcp-data

你可以使用 TELEGRAM_DATA_PATH 環境變量覆蓋此設置。

🛡️ 安全注意事項

• 切勿提交你的 .env 文件 - 其中包含敏感的 API 憑證
• API 憑證是個人的 - 每個用戶都需要自己的憑證
• 會話文件包含認證數據 - 請妥善保管
• 使用 .gitignore 文件防止意外提交

📝 開發

# 以開發模式運行
npm run dev

# 構建項目
npm run build

# 監聽文件變化
npm run watch

🤝 貢獻

歡迎貢獻代碼！請按以下步驟操作：

1. 分叉此倉庫
2. 創建一個功能分支
3. 進行更改
4. 提交拉取請求

📄 許可證

本項目採用 MIT 許可證 - 詳情請參閱 LICENSE 文件。

🙏 致謝

本項目基於以下工具構建：

• 模型上下文協議 SDK
• GramJS - Telegram 客戶端庫
• Puppeteer - 瀏覽器自動化工具

⚠️ 免責聲明

本工具僅用於教育和研究目的。請遵守 Telegram 的服務條款和頻道成員的隱私。在抓取私有頻道之前，請務必獲得許可。

🐛 故障排除

API 模式問題

• “未連接到 Telegram API”：先運行 telegram_api_login
• 電話號碼格式：請包含國家代碼（例如 +1234567890）
• 2FA 錯誤：提示時輸入你的 2FA 密碼

網頁抓取問題

• “未找到 Chrome 二進制文件”：安裝 Chrome 或 Chromium
• 登錄問題：確保使用正確的電話號碼格式
• 超時錯誤：在 .env 文件中增加 BROWSER_TIMEOUT

📞 支持

• 在 GitHub 上創建問題報告錯誤
• 創建新問題前先檢查現有問題
• 報告問題時請包含錯誤消息和日誌