AI导哈

Telegram MCP服务

通过MTProto协议将Telegram账户功能暴露为AI代理工具，支持消息搜索、媒体下载等操作。

  • by newink
  • TypeScript
  • 本地部署
  • 12 星标
  • 更新于
在 GitHub 查看 newink/telegram-mcp

使用说明

电报mcp

让人工智能代理访问您的Telegram-通过MTProto，而不是Bot API。

这是什么？

电报mcp 是一个 MCP服务器 这会将您的Telegram帐户暴露为AI代理的工具。使用 MTProto （userbot协议）-而不是Bot API-这意味着它可以访问您的帐户可以访问的任何聊天、频道或DM，而无需添加机器人程序。

将其连接到Claude、Codex或任何兼容MCP的客户端，让代理读取消息、搜索对话框、下载媒体和获取消息链接——所有这些都可以从您的个人电报中完成。

用例

📰 频道摘要 让你的客服从你最喜欢的科技频道中提取最后50条未读消息，过滤内容，并总结值得一读的内容。

"Fetch unread messages from @some_channel since yesterday and summarize the key points"

🔍 搜索您的历史记录 在500人的小组中，找到三周前有人发给你的链接。

"Search my dialogs for 'MCP server' and find where I discussed it"

🤖 代理收件箱监控 连接你的人工智能代理，定期检查特定频道，并将有趣的内容导入你的工作流程——笔记、捕获文件、摘要。

📎 媒体提取 从代理发现的任何消息中下载文件、图像或文档，这对自动化研究流程很有用。

工具

工具 说明
search_dialogs 按姓名或用户名搜索聊天记录、群组和频道
get_messages 获取具有日期范围、未读筛选器和标记为已读支持的邮件
search_messages 在所有聊天或特定聊天中进行全文搜索
media_download 将消息中的媒体（照片、视频、文档）下载到本地文件
message_from_link 按以下方式获取消息 t.me/... 链接
delete_messages 从聊天中删除消息（需要通过选择加入 bot-data/config.yml)
send_message 向聊天室发送短信（需要通过以下方式选择加入 bot-data/config.yml)
send_file 将本地文件作为文档发送到聊天室（需要通过以下方式选择加入 bot-data/config.yml)

参数和示例的完整参考→ docs/tools.md

快速开始

1.获取Telegram API证书

首选 my.telegram.org，创建一个应用程序，然后抓取您的 API_ID 和 API_HASH.

2.安装

git clone https://github.com/newink/telegram-mcp.git
cd telegram-mcp
bun install

cp .env.example .env
# Fill in TELEGRAM_API_ID and TELEGRAM_API_HASH

3.通过浏览器启动和授权

bun start

如果没有配置会话，服务器将在设置模式下启动并打印一个身份验证URL：

WARN: auth required — open URL to connect Telegram account
      url: "http://localhost:3000/auth?token=a3f9b2c1-..."

在浏览器中打开URL，您将看到一个身份验证页面，您可以在其中使用 二维码 （用Telegram扫描→ 设置→ 设备→ 链接桌面设备）或您的 电话号码登录后，会话将保存到 .env 服务器已准备就绪。

一次性代币 --the /auth URL在每次服务器启动时仅有效一次，并在成功登录后过期。重新启动服务器会生成一个新令牌。

就是这样。将您的MCP客户端指向 http://localhost:3000/mcp.

更喜欢终端？使用 bun run auth

bun run auth
# Interactive CLI: QR code or phone number, saves session to .env
bun start

两个流程都会产生相同的结果——选择适合您设置的一个。

码头工人

使用Docker Compose运行——无需安装Bun：

cp .env.example .env
# Fill in TELEGRAM_API_ID and TELEGRAM_API_HASH

docker compose up

第一次启动容器时，没有 TELEGRAM_SESSION，它将打印一个身份验证URL——在浏览器中打开它进行登录。会话将持久化到 ./bot-data/ 所以你只需要认证一次。

Manual docker run 
docker build -t telegram-mcp .

docker run -p 3000:3000 \
  --env-file .env \
  -e ENV_FILE=/app/bot-data/.env \
  -v ./bot-data:/app/bot-data \
  telegram-mcp

拉取预构建图像

# Latest stable
docker pull newink/telegram-mcp

# Or from GitHub Container Registry
docker pull ghcr.io/newink/telegram-mcp

支持的平台： linux/amd64, linux/arm64 （Raspberry Pi、苹果Silicon通过Rosetta）。

连接到您的AI客户端

克劳德桌面版

先启动服务器(bun start)，然后添加到 claude_desktop_config.json:

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

mcporter/OpenClaw

{
  "mcpServers": {
    "telegram": {
      "baseUrl": "http://localhost:3000/mcp"
    }
  }
}

直接HTTP（任何客户端）

# Initialize session first, then call tools:
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_dialogs","arguments":{"query":"news"}}}'

环境变量

变量 必填 描述
TELEGRAM_API_ID 是* 来自 my.telegram.org
TELEGRAM_API_HASH 是* 来自 my.telegram.org
TELEGRAM_SESSION 是* 由浏览器身份验证生成或 bun run auth
PORT 无 服务器端口（默认值： 3000)
LOG_LEVEL 否 引脚日志级别： trace|debug|info|warn|error （默认值： info)
TELEGRAM_MOCK 否 设置 true 使用模拟数据（不需要真正的Telegram）

*在以下情况下不需要 TELEGRAM_MOCK=true.

发展

bun dev              # Start with hot reload
bun test             # Run tests (uses mock automatically)
bun run typecheck    # TypeScript check
bun run lint         # Biome lint + format
bun run lint:fix     # Auto-fix lint issues
bun run knip         # Find dead code
bun run audit        # Full health check (types + lint + structure + TODOs)

模拟模式 --在没有真实Telegram帐户的情况下进行开发和测试：

TELEGRAM_MOCK=true bun dev   # server with fake data
TELEGRAM_MOCK=true bun test  # run tests

模拟数据包括示例对话框、消息和媒体，足以在不接触真正的API的情况下构建和测试新工具。

项目结构和架构→ docs/architecture.md MTProto的细节和问题→ docs/mtproto.md 添加新工具→ docs/tools.md

构建于

许可证

麻省理工学院

相关 MCP