telegram-ads

Agent plugin for ads.telegram.org: typed tools, Playwright login, read-only watcher.

Current release: v0.3.6 (MIT).

Give your agent the git URL. It installs itself. You do not host an MCP server.

Supports the 2026-08 beta create form: Search / Bots / Users / Channels (cannot mix types on one ad). Video upload on Users + Channels. TON geo hard-block RU/UA/IL/PS. Targeting is immutable after create.

Watcher ticks are silent. It wakes the same conversation that created the watch, and only when the watch condition is met. Do not use Hermes cron for Ads polling — even [SILENT] cron still writes a new session every tick.

MCP is local

The MCP entrypoint is a stdio child process the agent starts:

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

No public port, no VPS daemon, no URL to keep alive. Chromium runs on the same machine as the agent. Same rule as Playwright MCP.

Related MCP server: telegram-user-mcp

Install

Hermes Agent

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

Then follow after-install.md (venv pip, playwright install chromium, TELEGRAM_ADS_PHONE, gateway restart, telegram_ads_login_from_env + Accept in Telegram).

Grant watcher inject so the read-only watcher can wake a chat:

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

Set TELEGRAM_ADS_PHONE in the environment. First mutating call uses Claude Code's own permission prompt (Hermes Once/Session/Always cards exist only on Hermes).

Other MCP agents (Cursor, …)

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

Point the agent at this checkout:

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

First login (every host)

1. TELEGRAM_ADS_PHONE in the host env (never in git).

2. Call telegram_ads_login_from_env.

3. Tap Accept in the Telegram app.

4. Cookies stay in the persistent Chromium profile (TELEGRAM_ADS_HOME, or ~/.hermes/data/telegram_ads if Hermes is present, else ~/.telegram-ads).

Safety

• Mutations require host approval (Hermes Once/Session/Always/Deny, or the MCP client's permission UI). Do not confirm by typing "yes".

• Watcher is read-only. Do not start a second Playwright on the same Ads profile.

• Do not start a second Telegram getUpdates poller. This plugin reuses the host bot.

• Do not bind hermes serve / MCP HTTP on 0.0.0.0.

Not in this plugin

Telegram research (Telethon), GrokBot identity, channel portfolio, /sessions. Those stay on the operator host.

Changelog

See CHANGELOG.md.

License

MIT