🇬🇧  ·  🇷🇺

telegram-ads-mcp
MCP server for Telegram Ads. Currency: Gram (TON) 💎

Create, target, pause, and read stats from ads.telegram.org — from Claude, Cursor, or any MCP client.
Cookies stay in .env. Never paste them into chat. DevTools clicks: INSTALL.md.

★ Star  ·  Install (for agents)  ·  Playbook

---

Why

Telegram does not publish an advertiser API. This server wraps the logged-in ads.telegram.org session (stel_token / stel_ssid in a gitignored .env) and exposes ~25 MCP tools, plus ads://playbook and ads://account.

Live cabinet is TON, billed in Gram. User-geo (target_type=users) works. Stars cabinets are refused (code: stars_cabinet). Unofficial — not Telegram.

Write permission is .env TG_ADS_WRITE_GATE=strict|confirm|open (default confirm). Spend/destructive tools need confirm=true unless open. A blocked call returns code: write_gated with tool / class / would_send (intended args, no secrets) and sent: false — not a platform dry-run.

What's new in 0.3.0

• Stats. get_ad_stats echoes request period (5min = last 24h, day = lifetime). summary.spend and charts.budget are already scaled — do not divide. No CSV tool; optional dump is gitignored reports/.
• Session. Dead cookies: follow INSTALL.md DevTools clicks into .env only, then reload_session. Never paste values into chat.
• Bugs. Offer a GitHub Issue (playbook Found a bug → Issue). Local draft: uv run python scripts/check_security.py --issue draft.md (prints gh issue create, does not open).
• Audience / events. Access denied → code: access_denied, hint: skip. Do not retry.
• Create. launch_ad takes topics, exclude_*, locations. Do not send langs with specific channel IDs (platform Target invalid).
• Later RK service. JSON Schema in the wheel (telegram_ads_mcp/schemas/) names campaign brief / review / stats dump. This repo is not that service.
• Local notes. AGENTS.local.md is gitignored. Client playbook stays AGENTS.md. MCP JSON without secrets: mcp.json.example.

Quick start

git clone https://github.com/zai-one/telegram-ads-mcp.git
cd telegram-ads-mcp
uv sync
cp .env.example .env    # STEL_TOKEN / STEL_SSID — DevTools steps in INSTALL.md; never paste into chat

{
  "mcpServers": {
    "telegram-ads": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/telegram-ads-mcp", "run", "telegram-ads-mcp"]
    }
  }
}

Agent setup (clone, config, star): copy INSTALL.md into the chat. Command: telegram-ads-mcp (alias tg-ads-mcp). After connect: ads://playbook. Prompts: launch-campaign, review-account, diagnose-ad. Client file names are in INSTALL.md (Cursor, Claude, VS Code servers, Codex TOML). Do not put cookies in MCP env. Example: mcp.json.example.

HTTP: uv run telegram-ads-mcp --transport streamable-http --host 127.0.0.1 --port 8000 → http://127.0.0.1:8000/mcp.

Tools

Area	Tools
Auth	check_session reload_session list_accounts select_account get_account
Ads	get_ads get_ad get_ad_stats create_ad edit_ad delete_ad clone_ad launch_ad check_ad_post send_target_to_review
Creatives	upload_media preview_ad
Targeting	search_targets get_targeting_reference
Other	manage_audience manage_event manage_funds save_api_settings revoke_token log_out

Always create ads on_hold. budget="0" cannot go to review. Amounts are Gram strings. Search ads: no text / picture / media. launch_ad does not activate; it adds budget and sends review. Do not combine langs with specific channels.

Issues

I'm working on this. If something is missing or broken, open an issue. I will patch this repo.

Use the form. Tick both “no cookies / no hashes” boxes. Never paste stel_token, stel_ssid, .env, confirm_hash, API hash=, or DevTools screenshots.

Local draft: uv run python scripts/check_security.py --issue draft.md — prints gh issue create only if the draft is clean. It does not open the Issue.

Support is not guaranteed. Issues are read when I can.

Need EUR or Stars cabinets (not live here)? Write on Telegram: t.me/zai_one. We can talk about access. Do not send cookies in the GitHub issue.

Built by ZAI.ONE

ZAI.ONE is a digital agency working on websites, SEO, advertising and analytics. We also build tools that connect AI assistants to everyday work. Talk to us on Telegram about setup, automation or an integration for your team.

LicenseRef-ZAI-ONE · LICENSE · SECURITY.md · open an issue