JinDaGe - telegram-mcp-server MCP Details

article

README

🚀 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 模式） - 在此获取

🛠️ 安装步骤

克隆此仓库：

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

安装依赖：

npm install

复制示例环境文件：

cp .env.example .env

编辑 .env 文件并添加配置：
- 对于 API 模式：添加你的 TELEGRAM_API_ID 和 TELEGRAM_API_HASH
- 对于网页抓取模式：默认设置即可使用
构建项目：

npm run build

🔧 配置

获取 Telegram API 凭证

访问 https://my.telegram.org
使用你的电话号码登录
点击“API 开发工具”
创建一个新应用
将 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 模式工具

telegram_api_login - 与 Telegram 进行认证（仅首次需要）

使用 telegram_api_login 连接到 Telegram

api_scrape_channel - 抓取频道帖子（默认无限制）

使用 api_scrape_channel，参数 url="https://t.me/channelname"

也可以设置限制：

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

api_search_channel - 在频道内搜索

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

网页抓取工具

scrape_channel - 抓取公共频道

使用 scrape_channel，参数 url="https://t.me/channelname"

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

🤝 贡献

欢迎贡献代码！请按以下步骤操作：

分叉此仓库
创建一个功能分支
进行更改
提交拉取请求

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

🙏 致谢

本项目基于以下工具构建：

模型上下文协议 SDK
GramJS - Telegram 客户端库
Puppeteer - 浏览器自动化工具

⚠️ 免责声明

本工具仅用于教育和研究目的。请遵守 Telegram 的服务条款和频道成员的隐私。在抓取私有频道之前，请务必获得许可。

🐛 故障排除

API 模式问题

“未连接到 Telegram API”：先运行 telegram_api_login
电话号码格式：请包含国家代码（例如 +1234567890）
2FA 错误：提示时输入你的 2FA 密码

网页抓取问题

“未找到 Chrome 二进制文件”：安装 Chrome 或 Chromium
登录问题：确保使用正确的电话号码格式
超时错误：在 .env 文件中增加 BROWSER_TIMEOUT

📞 支持

在 GitHub 上创建问题报告错误
创建新问题前先检查现有问题
报告问题时请包含错误消息和日志

telegram-mcp-server