telegram-ads

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

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

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: OpenAI Ads 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.

License

MIT