telegram-ads

用于 ads.telegram.org 的智能体插件：类型化工具、Playwright 登录、只读监视器。

将 Git URL 交给你的智能体即可。它会自行安装。你无需托管 MCP 服务器。

MCP 是本地化的

MCP 入口是一个stdio 子进程，由智能体启动：

agent  --stdin/stdout JSON-RPC-->  python -m hermes_telegram_ads.mcp

没有公共端口，没有 VPS 守护进程，没有需要保持存活的 URL。Chromium 与智能体运行在同一台机器上。规则与 Playwright MCP 相同。

Related MCP server: telegram-user-mcp

安装

Hermes

hermes plugins install https://github.com/sh0tn1k/telegram-ads.git --enable

然后按照 after-install.md 操作（venv pip、playwright install chromium、TELEGRAM_ADS_PHONE、网关重启、telegram_ads_login_from_env + 在 Telegram 中点击接受）。

授予 watcher 注入权限，以便只读监视器可以唤醒聊天：

plugins:
  entries:
    telegram-ads:
      allow_gateway_injection: true

Claude Code

/plugin marketplace add https://github.com/sh0tn1k/telegram-ads.git
/plugin install telegram-ads@telegram-ads

在环境中设置 TELEGRAM_ADS_PHONE。首次变更调用会使用 Claude Code 自身的权限提示（Hermes 的 Once/Session/Always 卡片仅存在于 Hermes 中）。

其他 MCP 智能体（Cursor 等）

pip install -e '.[mcp]'
python -m playwright install chromium

将智能体指向此代码库：

{
  "mcpServers": {
    "telegram-ads": {
      "command": "python",
      "args": ["-m", "hermes_telegram_ads.mcp"]
    }
  }
}

首次登录（每台主机）

1. 在环境中设置 TELEGRAM_ADS_PHONE（切勿写入 git）。

2. 调用 telegram_ads_login_from_env。

3. 在 Telegram 应用中点击接受。

4. Cookie 保存在持久化的 Chromium 配置文件中（TELEGRAM_ADS_HOME，若存在 Hermes 则为 ~/.hermes/data/telegram_ads，否则为 ~/.telegram-ads）。

安全

• 变更操作需要主机批准（Hermes 的 Once/Session/Always/Deny，或 MCP 客户端的权限界面）。不要通过输入“yes”来确认。

• Watcher 是只读的。不要在同一个 Ads 配置文件上启动第二个 Playwright 实例。

• 不要启动第二个 Telegram getUpdates 轮询器。此插件复用主机机器人。

• 不要将 hermes serve / MCP HTTP 绑定到 0.0.0.0。

本插件不包含的内容

Telegram 研究（Telethon）、GrokBot 身份、频道组合、/sessions。这些保留在操作员主机上。

许可证

MIT