telegram-ads-mcp
Summary: telegram-ads-mcp is an MCP server that wraps a logged-in ads.telegram.org session to let AI clients manage Telegram Ads campaigns (26 tools) — create, target, pause, and read stats.
Auth & account: check the session (
check_session), reload cookies (reload_session), list/switch cabinets (list_accounts,select_account), read cabinet currency, balance and write gate (get_account).Ads management: list/fetch ads (
get_ads,get_ad), create (create_ad), edit copy/CPM/budget/pause (edit_ad), delete (delete_ad), clone with same targeting (clone_ad), launch on hold with budget + review (launch_ad), validate post (check_ad_post), resubmit targeting (send_target_to_review).Creatives: upload photos/videos (
upload_media) and render a preview PNG (preview_ad).Targeting: resolve channels, bots, queries, locations to IDs (
search_targets) and look up countries/languages/topics taxonomies (get_targeting_reference).Stats: views, clicks, CTR, CPC, CPM, spend for one ad, last 24h or lifetime, summary/full/csv (
get_ad_stats).Audiences, events & pixels: list/create/rename/delete/clone audiences (
manage_audience); list/create/rename/delete conversion events and pixels (manage_event).Funds: list/search accounts, top-up requests, transfers and withdrawals (
manage_funds).Cabinet API settings: set IP whitelist (
save_api_settings), revoke/regenerate API token (revoke_token), log out (log_out).Maintenance: check for newer releases (
check_update) — suggests only, never installs.
Safety notes: ads are created on_hold; spend/destructive calls need confirm=true unless the write gate is open (default confirm); cookies stay in .env, never in chat or tool args.
Provides tools for managing Telegram Ads campaigns, including creating, targeting, pausing, cloning, and reading statistics through ads.telegram.org.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@telegram-ads-mcp Show me the stats for my active Telegram Ads campaigns."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 byget_account.Targeting references and
search_targetsso 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 |
| Source |
Claude Code | Supported (interactive: tools, prompts, resources; | |
VS Code (GitHub Copilot) | Supported (dynamic tool discovery); new tools may reach the agent only on the next turn | |
Gemini CLI | Supported (refreshes the tool registry) | |
Cursor | Unreliable: staff confirm a regression in 3.12.x; restart Cursor after enabling | |
Claude Desktop, Windsurf, Codex CLI, Cline, Zed, Continue | Unverified: no official statement found; use | — |
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=1turns 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_adsandget_ad_statsreturndetail="summary"by default: no null/empty fields, no per-bucketcharts. Passdetail="full"for the previous payload.Safer
.env. From the working folder's.envonlySTEL_*cookies are read (no parent walk); settings come fromTG_ADS_ENV_FILE, the clone's.envor the process environment.Agent layer. Router instructions, skills (launch / review / diagnose),
ads://guide/{topic}, errorhint/docs, Claude Code and Cursor plugins pinned tov0.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-mcpCursor: 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 |
|
Ads |
|
Creatives |
|
Targeting |
|
Other |
|
Updates |
|
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 toolscheck_ad_postValidate ad postARead-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 sessionARead-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 updateARead-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 adADestructive
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 cabinetARead-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 adARead-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 adsARead-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 statsARead-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 referenceARead-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 cabinetsARead-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 outADestructive
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 fundsADestructive
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 adARead-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 tokenADestructive
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 targetsARead-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
Scored across 26 tools
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.
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.
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.
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
Related MCP Connectors
60+ Meta Ads tools for AI agents: audits, campaign management, audiences and CAPI tracking.
Open-source ad agent for LinkedIn Ads and Google Ads. Drafts campaigns, audiences and reports.
Manage Google, Meta, Amazon, TikTok, LinkedIn & ChatGPT ads. 430 tools for campaigns & analytics.
The simplest way to manage your Meta (Facebook and Instagram) ad accounts with your AI agent.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceEnables 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.2Apache 2.0
- 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
- FlicenseAqualityDmaintenanceEnables 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-
- AlicenseNot gradedqualityCmaintenanceEnables 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 npmMIT