Telegram Ads MCP
reputasyon/telegram-ads-mcp
Gerenciar campanhas Telegram Ads através do Claude
Ver no GitHubMCP server para integrar a plataforma de anúncios do Telegram (ads.telegram.org) com Claude e outros clientes MCP. Permite listar anúncios, consultar estatísticas, buscar canais-alvo e criar/rascunhar mensagens patrocinadas diretamente via IA, usando autenticação por cookies de sessão.
Instalação
npx convez-ai reputasyon/telegram-ads-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automatizar criação e gestão de anúncios no Telegram
- Consultar estatísticas e performance de campanhas em tempo real
- Pesquisar e validar canais públicos para segmentação de audiência
- Rascunhar e revisar anúncios antes de publicação
Veredito

Ferramenta poderosa mas com ressalvas críticas: funciona via API interna não-oficial do Telegram, pode quebrar sem aviso, requer autenticação manual por cookies e movimenta TON real. Ideal para builders que precisam automatizar campanhas Telegram em larga escala, mas exige cautela legal e técnica.
README
A tradução para o português deste README ainda está na fila.
Telegram Ads MCP
A Model Context Protocol server for the Telegram Ad Platform (https://ads.telegram.org). It lets an MCP client (Claude Code, Claude Desktop, etc.) list ads, read statistics, find target channels, and create / draft sponsored messages.
[!WARNING] Unofficial. Telegram does not publish an Ads API. This server wraps the internal API used by the ads.telegram.org web interface, authenticating with your browser session cookies. It is not affiliated with or endorsed by Telegram, may break at any time if Telegram changes the web app, and can spend real TON. Use at your own risk and review Telegram's Ad Policies and Terms of Service.
How it works
- Auth uses your logged-in session cookies (
stel_ssid,stel_token,stel_adowner). No official token exists. - Every request is
POST https://ads.telegram.org/api?hash=<hash>with a form-encodedmethod. The sessionhashis scraped automatically from the/accountpage — no extra configuration.
Setup
1. Get your cookies
Log in to https://ads.telegram.org/account in your browser, open DevTools →
Application/Storage → Cookies → https://ads.telegram.org, and copy the
values of:
stel_ssidstel_tokenstel_adowner
2. Configure
git clone https://github.com/reputasyon/telegram-ads-mcp
cd telegram-ads-mcp
npm install
cp .env.example .env # then paste your cookies into .env
.env:
TG_ADS_COOKIE="stel_ssid=...; stel_token=...; stel_adowner=..."
Cookies last a long time but do expire; if you get a "session looks invalid" error, refresh them from the browser.
3. Register with your MCP client
Claude Code (.mcp.json in your project, or claude mcp add):
{
"mcpServers": {
"telegram-ads": {
"command": "node",
"args": ["/absolute/path/to/telegram-ads-mcp/index.js"]
}
}
}
Claude Desktop uses the same shape in claude_desktop_config.json.
Tools
| Tool | Description |
|---|---|
list_ads | List ads, balance and overall account status |
get_ad | Read a single ad's detail / statistics |
search_channel | Validate a channel for targeting (returns its val token) |
similar_channels | Suggest channels similar to the given ones |
save_draft | Save an ad as a draft (no review, no spend) |
create_ad | Create an ad — defaults to paused/On Hold |
raw_api | Raw call to an arbitrary API method |
get_page | Fetch any ads.telegram.org page as plain text |
Notes & gotchas
- Budget and CPM are in TON (💎). Ad text is max 160 characters.
- You can promote a Telegram link (
t.me/...) or an external URL (shown with awebsite_nameabove the text). - Target channels must be public with 1000+ subscribers. Your own small channel can still be the promoted destination, just not a target.
- Channel targeting uses
valtokens fromsearch_channel. The server only accepts tokens resolved in the same session, so search the channels right before callingcreate_ad. - With
target_type=channels, do not setlangs— it conflicts and the API returnsTarget invalid. The channels already define the audience. - New ads go through Telegram review before going live.
create_addefaults toactive=false(created paused) so nothing is spent until you explicitly publish.
License
MIT — see LICENSE.