Skip to main content
Glama
telegram-ads-mcp

telegram-ads-mcp

by zai-one

MCP server for the Telegram Ads platform (ads.telegram.org, TON cabinet): create, target, pause and read stats for ads; 26 tools, new ads start on hold.

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 26 MCP tools, plus ads://playbook and ads://account.

Cabinets: TON (billed in Gram), EUR and Stars (whole-number amounts, no user targeting; opt-in with TG_ADS_STARS=on). get_account returns money rules; bad amounts are rejected before any call. 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.

Related MCP server: telegram-ads-mcp

Why this MCP

  • Optional lazy tool loading: set TG_ADS_TOOL_LOADING=lazy (or choose it in the setup wizard) to start with a small core and enable toolsets on demand; see Lazy tool loading.

  • Money safety: ads are created on_hold; spending actions go through a write gate shown by get_account.

  • Targeting references and search_targets so the agent never guesses IDs; 3 prompts, 3 resources incl. ads://playbook.

  • Session cookies stay in .env, never in chat.

  • Other Telegram Ads MCP servers on GitHub: Free-cat/telegram_ads_mcp (14 tools), reputasyon/telegram-ads-mcp (8 tools).

Lazy tool loading

Optional lazy tool loading: TG_ADS_TOOL_LOADING=lazy starts with a small core plus tg_ads_enable_toolsets and adds toolsets on demand (tools/list_changed). Startup cost (tools/list + instructions, ≈chars/4): eager ≈7262 tokens, lazy ≈1748 tokens (−76%). Default eager is unchanged; if your client ignores tools/list_changed, keep eager or reconnect after enabling. Scope: enablement is process-wide (the MCP SDK MCPServer has no per-session tool visibility). Over stdio that is one client; in shared HTTP mode one client's enabled toolsets are listed for every client of that process (each call still passes its own gates), so use eager for shared HTTP.

Clients and notifications/tools/list_changed (verified against official docs, changelogs or maintainer statements, 2026-10):

Client

tools/list_changed

Source

Claude Code

Supported (interactive: tools, prompts, resources; -p/Agent SDK: tools)

docs: Dynamic tool updates

VS Code (GitHub Copilot)

Supported (dynamic tool discovery); new tools may reach the agent only on the next turn

docs, #303012

Gemini CLI

Supported (refreshes the tool registry)

PR #14375, PR #21050

Cursor

Unreliable: staff confirm a regression in 3.12.x; restart Cursor after enabling

forum

Claude Desktop, Windsurf, Codex CLI, Cline, Zed, Continue

Unverified: no official statement found; use eager or reconnect after enabling

—

Maintained and up to date

  • Actively maintained by ZAI.ONE: current version 0.6.0; release notes in CHANGELOG.md and Releases.

  • Built-in update check: ask the assistant to run check_update (public GitHub API, no credentials, cached; nothing is installed automatically; TG_ADS_DISABLE_UPDATE_CHECK=1 turns it off).

  • Follows current MCP practice: tool annotations (read-only / destructive hints), server instructions, prompts and resources, structured errors with recovery hints, secrets kept out of tool output, a token budget for tool descriptions enforced in tests.

  • CI runs the test suite on Linux and Windows for every pull request.

What's new in 0.5.0

  • Compact output. get_ads and get_ad_stats return detail="summary" by default: no null/empty fields, no per-bucket charts. Pass detail="full" for the previous payload.

  • Safer .env. From the working folder's .env only STEL_* cookies are read (no parent walk); settings come from TG_ADS_ENV_FILE, the clone's .env or the process environment.

  • Agent layer. Router instructions, skills (launch / review / diagnose), ads://guide/{topic}, error hint / docs, Claude Code and Cursor plugins pinned to v0.5.0.

  • License. LicenseRef-ZAI-ONE 2.0 (source-available); earlier MIT releases stay MIT (see NOTICE).

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.

Install anywhere (uvx, plugins)

Cookies stay in a .env file on disk (never in MCP env values or chat). For uvx installs point TG_ADS_ENV_FILE at that file (path only), or start the client from a folder that has .env. From the working folder's .env (that folder only, not its parents) the server takes STEL_* cookies and nothing else; settings such as TG_ADS_WRITE_GATE, MCP_TRANSPORT / MCP_HOST / MCP_PORT or TG_ADS_DISABLE_UPDATE_CHECK are read only from TG_ADS_ENV_FILE, the clone's own .env, or the process environment, so an unrelated project's .env cannot open the write gate or expose the server on the network.

# Claude Code: MCP only
claude mcp add telegram-ads --env TG_ADS_ENV_FILE=/path/to/telegram-ads.env -- uvx --from git+https://github.com/zai-one/telegram-ads-mcp@v0.6.0 telegram-ads-mcp
# Claude Code: plugin = MCP + skills (launch / review / diagnose)
/plugin marketplace add zai-one/telegram-ads-mcp
/plugin install telegram-ads@telegram-ads-mcp

Cursor: one-click install or .cursor/mcp.json:

{"mcpServers": {"telegram-ads": {"command": "uvx", "args": ["--from", "git+https://github.com/zai-one/telegram-ads-mcp@v0.6.0", "telegram-ads-mcp"], "env": {"TG_ADS_ENV_FILE": "/path/to/telegram-ads.env"}}}}

Codex ~/.codex/config.toml:

[mcp_servers.telegram-ads]
command = "uvx"
args = ["--from", "git+https://github.com/zai-one/telegram-ads-mcp@v0.6.0", "telegram-ads-mcp"]
env = { TG_ADS_ENV_FILE = "/path/to/telegram-ads.env" }

Claude Desktop claude_desktop_config.json: the same mcpServers block as Cursor. Skills for Codex and other hosts: copy skills/* into .agents/skills/.

Skills: telegram-ads-launch-campaign, telegram-ads-review-account, telegram-ads-diagnose-ad (mirrored by the prompts). Guides on demand: ads://guide/index → ads://guide/{topic}.

Example asks: "Review my Telegram Ads cabinet", "Launch an ad for t.me/my_channel with CPM 0.5 and budget 5 Gram", "Why does ad 35 get no views?", "Pause ad 35", "Show stats for ad 35 for its lifetime".

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

Updates

check_update

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.

Updates. check_update compares your version with the latest release and returns the release notes link plus the command to run (git pull --ff-only && uv sync in a clone, otherwise pip install --upgrade "telegram-ads-mcp @ git+…@vX"). run_in says where to run it. It only suggests and never installs. Only plain version tags (v1.2.3) are accepted. One anonymous GitHub API call, 3 s timeout, cached 24 h; after a failed call it waits 30 min, and force=true re-checks at most once a minute; offline returns status: unavailable. When the cache knows of a newer release, check_session adds update_hint and the server instructions get one line. At startup (stdio and HTTP alike) the server itself calls api.github.com anonymously, at most once a day, unless disabled; for a server or firewalled deployment set TG_ADS_DISABLE_UPDATE_CHECK=1 in .env or the process environment.

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.

EUR and Stars support is fixture-tested; found a mismatch on a live EUR/Stars cabinet? Write on Telegram: t.me/zai_one. 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

License, use and contributing

  • Use: you may install and use this MCP server freely for yourself and your organisation, including commercial work. If it helps, please consider giving the repository a ⭐ — appreciated, never required.

  • Contribute: issues and pull requests are welcome; see CONTRIBUTING.md. Never post tokens, cookies, sessions or account data.

  • Not allowed without written permission from ZAI.ONE: copying code into other projects, forking for redistribution, embedding the server in other products or offering it as a competing service.

  • License: LicenseRef-ZAI-ONE 2.0 (source-available, not open source). Third-party notices and license history: NOTICE.

Available Tools

26 tools
check_ad_postValidate ad postA
Read-onlyIdempotent

Validate promote_url and text before create or launch. Use before launch_ad/create_ad. Read-only. Returns ok or the platform error text.

Inputs: promote_url (required), text. Returns: object

check_sessionCheck sessionA
Read-onlyIdempotent

Ping the ads.telegram.org session. Use first in every chat; on ok=false code=auth offer INSTALL.md DevTools steps, then reload_session. Returns owner_id, cabinet, currency, balance, write_gate.

Inputs: no named parameters. Returns: object

check_updateCheck for updateA
Read-onlyIdempotent

Check GitHub for a newer telegram-ads-mcp release. Use when the user asks about updates. Suggest only, never install. Returns current, latest, command, run_in.

Inputs: force. Returns: object

clone_adClone adA

Duplicate an ad into a new on_hold draft with the same targeting. Use to change immutable targeting. Two-step confirm_hash; confirm=true for the gate. Returns the new ad id.

Inputs: ad_id (required), confirm, confirm_hash. Returns: object

create_adCreate ad (full)A

Create an ad on_hold with the full targeting field set. Prefer launch_ad for the normal flow. Writes: confirm=true if budget>0 or active (gate). IDs semicolon-separated; no langs with channels.

Inputs: cpm (required), title (required), promote_url (required), bots, +37 more. Returns: object

delete_adDelete adA
Destructive

Delete an ad (destructive). Two steps: call without confirm_hash, show the user, then call with the returned hash. confirm=true is the gate flag, not the hash. To pause use edit_ad.

Inputs: ad_id (required), confirm, confirm_hash. Returns: object

edit_adEdit adA

Edit only the fields passed: copy, CPM, pause/activate, budget_action+budget_amount or budget_target. budget_target is read back. Targeting is immutable, use clone_ad. Activate/budget need confirm=true.

Inputs: ad_id (required), cpm, text, media, +20 more. Returns: object

get_accountGet cabinetA
Read-onlyIdempotent

Read the current cabinet card. Use before any write to check currency and gate; for the ad list use get_ads. Returns owner_id, cabinet, currency (GRAM/EUR/XTR), money, balance, write_gate.

Inputs: no named parameters. Returns: object

get_adGet adA
Read-onlyIdempotent

Fetch one ad by id with full fields. Use for diagnosis; for metrics use get_ad_stats. Falls back to HTML/list when getAd returns 400. Returns the ad card.

Inputs: ad_id (required). Returns: object

get_adsList adsA
Read-onlyIdempotent

List ads, 100 per page, status=any|active|on_hold. Use for account overviews; for one ad use get_ad. Paginate with offset_id=next_offset_id. Returns ads with status, spent, cpm, budget.

Inputs: detail, status, offset_id. Returns: object

get_ad_statsAd statsA
Read-onlyIdempotent

Get views/clicks/CTR/CPC/CPM/spend for one ad. period=5min: last 24h; day: lifetime. summary.spend is already scaled (Gram); never divide. For many ads use get_ads. detail=full adds charts.

Inputs: ad_id (required), detail, period. Returns: object

get_targeting_referenceTargeting referenceA
Read-onlyIdempotent

List countries, languages, topics and channel taxonomies with IDs. Use for user-geo and topic targeting; for channels/bots use search_targets. Empty list means not embedded.

Inputs: kind. Returns: object

launch_adLaunch ad (on_hold)A

Create on_hold, add budget (default 1 Gram), send to review; never activates. Use for new ads; full targeting via create_ad. Spends: confirm=true unless gate=open. Returns per-step results.

Inputs: cpm (required), title (required), promote_url (required), bots, +22 more. Returns: object

list_accountsList cabinetsA
Read-onlyIdempotent

List ad cabinets for this Telegram login. Use to find owner_id before select_account; works on any cabinet (TON, EUR, Stars). Returns accounts.

Inputs: no named parameters. Returns: object

log_outLog outA
Destructive

Log out of ads.telegram.org; the user then needs fresh cookies in .env. Destructive; use only when explicitly asked. Never use it to fix auth.

Inputs: confirm. Returns: object

manage_audienceManage audiencesA

Custom audiences: action=list|create|rename|delete|clone. list is read-only; delete/clone use two-step confirm_hash plus gate confirm. code=access_denied means skip, do not retry.

Inputs: action (required), title, confirm, user_ids, +3 more. Returns: object

manage_eventManage eventsB

Conversion events and pixels: action=list|create|rename|delete|create_pixel. list is read-only; delete is destructive with two-step confirm_hash. code=access_denied means skip.

Inputs: action (required), title, confirm, event_id, +2 more. Returns: object

manage_fundsManage fundsA
Destructive

Funds: action=list|search (lookup), add (top-up request), transfer|withdraw (money moves now, no hash). Destructive: confirm=true and explicit user yes. Never guess account_id.

Inputs: action (required), query, amount, confirm, +2 more. Returns: object

preview_adPreview adA
Read-onlyIdempotent

Render a sponsored-message preview PNG and save it under ./previews (gitignored). Use to show the user the copy before launch or during diagnosis. Returns an image.

Inputs: ad_id (required).

reload_sessionReload sessionA

Re-read .env cookies and rebuild the HTTP session. Use after the user updated .env on disk; never pass cookie values as arguments. Returns ok and the new session card.

Inputs: no named parameters. Returns: object

revoke_tokenRevoke API tokenA
Destructive

Revoke and regenerate the cabinet API (IP-whitelist) token, not the ads cookies. Destructive; use only when the user asks. Never use it to fix auth.

Inputs: confirm. Returns: object

save_api_settingsSave API IP whitelistB

Set the newline-separated IP whitelist for the cabinet API token. Destructive; use only when the user asks. confirm=true unless gate=open.

Inputs: ip_list (required), confirm. Returns: object

search_targetsSearch targetsA
Read-onlyIdempotent

Resolve channels, bots, search queries, locations or similar_* to IDs. Use before launch/create; never guess IDs. purpose=target (placement) or promote (URL lookup). Returns the platform match list.

Inputs: kind (required), ids, query, region, +2 more. Returns: object

select_accountSelect cabinetA

Switch the active ad cabinet by owner_id from list_accounts. Use when the wrong or a Stars cabinet is active. Writes: confirm=true under gate strict. Then call get_account.

Inputs: owner_id (required), confirm. Returns: object

send_target_to_reviewSend to reviewA

Submit or resubmit an ad's targeting for moderation. Use after edits; launch_ad already does it. Needs non-zero budget. Spend-class: confirm=true unless gate=open.

Inputs: ad_id (required), confirm. Returns: object

upload_mediaUpload mediaA

Upload a photo (16:9, <5 MB) or video (MP4 3-60s, <20 MB) by file_path or media_base64. Use before create_ad/edit_ad media=. Returns the media hash.

Inputs: ad_id, confirm, filename, file_path, +1 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 26 tools

    Disambiguation4/5

    Descriptions are unusually explicit and cross-reference each other ('for one ad use get_ad', 'prefer launch_ad'), making most tools easy to select. The main overlap is create_ad vs launch_ad vs clone_ad, which all produce new ads, though the descriptions clearly delineate when to use each.

    Naming Consistency5/5

    All names are snake_case verb_noun (check_session, get_ads, create_ad, delete_ad, upload_media, search_targets), with a consistent 'manage_' prefix reserved for multi-action grouped tools (manage_audience, manage_funds, manage_event). The pattern is predictable throughout.

    Tool Count4/5

    26 tools is slightly heavy, but the domain (ads CRUD, session, funds, audiences, events, media, targeting, stats) genuinely needs this breadth and each tool targets a distinct operation. It sits just over the comfortable range but earns its count.

    Completeness4/5

    Coverage is strong: full ad lifecycle (create/edit/delete/clone/launch), audience/event/funds management, media upload, targeting resolution, stats, and session handling. Minor gaps exist (no explicit campaign-level operations), but core workflows are covered without dead ends.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI assistants to manage Google Ads accounts by providing tools for querying account data and performing write operations such as updating campaign budgets, statuses, and bidding strategies.
      2
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      An 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.
      11
      1
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Enables AI agents to manage Google Ads campaigns (Search and UAC) through natural language, with read tools always available and guarded write operations for budgets, campaigns, ad groups, and keywords.
      3
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to manage and analyze Google Ads campaigns through tools for listing campaigns, retrieving settings, performance metrics, ad groups, and running custom GAQL queries.
      81 npm
      MIT