telegram-ads

Agent-Plugin für ads.telegram.org: typisierte Tools, Playwright-Login, schreibgeschützter Watcher.

Gib deinem Agenten die Git-URL. Es installiert sich selbst. Du hostest keinen MCP-Server.

MCP ist lokal

Der MCP-Einstiegspunkt ist ein stdio-Kindprozess, den der Agent startet:

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

Kein öffentlicher Port, kein VPS-Daemon, keine URL, die man am Leben halten muss. Chromium läuft auf derselben Maschine wie der Agent. Gleiche Regel wie beim Playwright MCP.

Related MCP server: OpenAI Ads MCP

Installation

Hermes Agent

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

Folge dann der after-install.md (venv pip, playwright install chromium, TELEGRAM_ADS_PHONE, Gateway-Neustart, telegram_ads_login_from_env + „Accept“ in Telegram).

Gewähre „watcher inject“, damit der schreibgeschützte Watcher einen Chat aufwecken kann:

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

Setze TELEGRAM_ADS_PHONE in der Umgebung. Der erste ändernde Aufruf nutzt Claude Codes eigene Berechtigungsabfrage (die Hermes-Karten „Once/Session/Always/Deny“ gibt es nur auf Hermes).

Andere MCP-Agenten (Cursor, …)

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

Verweise den Agenten auf dieses Checkout:

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

Erste Anmeldung (auf jedem Host)

1. TELEGRAM_ADS_PHONE in der Host-Umgebung (niemals in Git).

2. Rufe telegram_ads_login_from_env auf.

3. Tippe in der Telegram-App auf „Accept“.

4. Die Cookies bleiben im persistenten Chromium-Profil (TELEGRAM_ADS_HOME bzw. ~/.hermes/data/telegram_ads, falls Hermes vorhanden ist, sonst ~/.telegram-ads).

Sicherheit

• Ändernde Vorgänge erfordern die Zustimmung des Hosts (Hermes „Once/Session/Always/Deny“ oder die Berechtigungsoberfläche des MCP-Clients). Bestätige nicht, indem du „yes“ tippst.

• Der Watcher ist schreibgeschützt. Starte kein zweites Playwright auf demselben Ads-Profil.

• Starte keinen zweiten Telegram-getUpdates-Poller. Dieses Plugin verwendet den Host-Bot erneut.

• Binde hermes serve / MCP HTTP nicht an 0.0.0.0.

Nicht in diesem Plugin enthalten

Telegram-Recherche (Telethon), GroGrokBot-Identität, Channel-Portfolio, /sessions. Diese bleiben auf dem Betreiber-Host.

Lizenz

MIT