telegram-ads
Provides tools for interacting with ads.telegram.org (Telegram Ads), enabling agents to manage ads, log in via Playwright, and monitor changes through a read-only watcher.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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.mcpNo 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-public-mcp-cloudflare
Install
Hermes Agent
hermes plugins install https://github.com/sh0tn1k/telegram-ads.git --enableThen 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: trueClaude Code
/plugin marketplace add https://github.com/sh0tn1k/telegram-ads.git
/plugin install telegram-ads@telegram-adsSet 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 chromiumPoint the agent at this checkout:
{
"mcpServers": {
"telegram-ads": {
"command": "python",
"args": ["-m", "hermes_telegram_ads.mcp"]
}
}
}First login (every host)
TELEGRAM_ADS_PHONEin the host env (never in git).Call
telegram_ads_login_from_env.Tap Accept in the Telegram app.
Cookies stay in the persistent Chromium profile (
TELEGRAM_ADS_HOME, or~/.hermes/data/telegram_adsif 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
getUpdatespoller. This plugin reuses the host bot.Do not bind
hermes serve/ MCP HTTP on0.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
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted Telegram MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Multi-tenant Telegram gateway for AI agents — HTTP+stdio, 8 tools, MTProto User API
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Hosted OpenAI Ads MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Related MCP Servers
- AlicenseBqualityDmaintenanceTyped MCP server for OpenAI Ads and ChatGPT Ads via the Advertiser API. Supports account, campaign, ad group, ad, creative, audience, insight, and conversion tools with readonly mode and guarded writes.124MIT
- AlicenseNot gradedqualityDmaintenanceReads public Telegram channel pages and exposes them as MCP tools over Streamable HTTP/JSON-RPC, enabling retrieval of channel info, latest posts, and search without Telegram API credentials.1MIT
- AlicenseAqualityDmaintenanceAn MCP server that lets AI agents read and manage Telegram Ads campaigns, including listing accounts and ads, reading stats and budgets, and creating/updating ads, CPM, status, and budget by driving the real ads.telegram.org web UI through Playwright with a reused cookie-based login session.111MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to drive a real Telegram account, exposing chats, messages, media, secret chats, admin rights, invite links, Mini Apps, and multi-account routing as callable tools.32GPL 3.0