convez.ai
MCP ServerMarketing & VendasAvançado
reputasyon

Telegram Ads MCP

reputasyon/telegram-ads-mcp

Gerenciar campanhas Telegram Ads através do Claude

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP 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-mcp

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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-encoded method. The session hash is scraped automatically from the /account page — 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_ssid
  • stel_token
  • stel_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

ToolDescription
list_adsList ads, balance and overall account status
get_adRead a single ad's detail / statistics
search_channelValidate a channel for targeting (returns its val token)
similar_channelsSuggest channels similar to the given ones
save_draftSave an ad as a draft (no review, no spend)
create_adCreate an ad — defaults to paused/On Hold
raw_apiRaw call to an arbitrary API method
get_pageFetch 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 a website_name above 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 val tokens from search_channel. The server only accepts tokens resolved in the same session, so search the channels right before calling create_ad.
  • With target_type=channels, do not set langs — it conflicts and the API returns Target invalid. The channels already define the audience.
  • New ads go through Telegram review before going live. create_ad defaults to active=false (created paused) so nothing is spent until you explicitly publish.

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados