Telegram Ads: MCP tool reference

The Valkiria MCP server at https://valkiria.pro/mcp gives a connected assistant 13 tools for accounts, ads, budgets and statistics in Telegram Ads. 13 of them only read. The assistant picks the tool itself; this page lists what exists, under the names it reports in its tool calls.

Checked:

01

Tools that read (13)

These only return data. They are not counted against the monthly allowance.

  • telegram_ads_drafts_list: List the user's saved Telegram Ads drafts (compact fields). Telegram Ads (ads.telegram.org): text <=160 chars with at most one @username or t.me link; the URL makes the button (Telegram sets its label). CPM (min 0.1) and budgets are in TON, never converted. Live changes happen only after the owner confirms them in /telegram-ads; write tools return a review link. Never invent a URL, channel, ad id or number. Statuses (draft, in_review, declined, active, on_hold, stopped, archived): for drafts linked to a live ad they are refreshed from the API on sync; otherwise they record what the user did in ads.telegram.org.
  • telegram_ads_policy_check: Deterministic pre-moderation check of a Telegram Ads text before saving. Returns ok plus issues {code,severity,explanation}; fix every error-level issue before saving. Telegram Ads (ads.telegram.org): text <=160 chars with at most one @username or t.me link; the URL makes the button (Telegram sets its label). CPM (min 0.1) and budgets are in TON, never converted. Live changes happen only after the owner confirms them in /telegram-ads; write tools return a review link. Never invent a URL, channel, ad id or number.
  • telegram_ads_stats: Read imported Telegram Ads statistics: per-ad totals (impressions, clicks, joins, spent_ton, ctr %, cpm_ton) and the daily series. Only what the user imported from an ads.telegram.org CSV; missing days are not zero. Amounts are TON, not converted. Telegram Ads (ads.telegram.org): text <=160 chars with at most one @username or t.me link; the URL makes the button (Telegram sets its label). CPM (min 0.1) and budgets are in TON, never converted. Live changes happen only after the owner confirms them in /telegram-ads; write tools return a review link. Never invent a URL, channel, ad id or number.
  • telegram_ads_launch: Launching or paying for Telegram Ads never happens from this tool. Returns a review link to /telegram-ads where the owner either creates the ad through the official API (connected account, explicit confirmation) or exports the draft manually. Export checklist: 1) Open ads.telegram.org and sign in with the account that holds TON. 2) Create a new ad and choose the targeting mode saved in the draft (channels, topics, bots or search). 3) Paste the ad text and URL exactly as saved (policy check passed). 4) Set CPM in TON (>= 0.1) and the budget; top up the TON balance in ads.telegram.org. 5) Submit for review, then record the Telegram ad ID and status on the draft in Valkiria (/telegram-ads). 6) Later export the statistics CSV from ads.telegram.org and import it in Valkiria.
  • telegram_ads_account: Live Telegram Ads account summary via the official API: connected, title, currency (TON/EUR/XTR), remainingBudget (balance), adsBudget, spentBudget, lastSyncedAt. connected:false means the user has not pasted an API token in /telegram-ads. Amounts are in the account currency, never converted. Telegram Ads (ads.telegram.org): text <=160 chars with at most one @username or t.me link; the URL makes the button (Telegram sets its label). CPM (min 0.1) and budgets are in TON, never converted. Live changes happen only after the owner confirms them in /telegram-ads; write tools return a review link. Never invent a URL, channel, ad id or number.
  • telegram_ads_remote_ads: ALL ads of the connected Telegram Ads account in ONE call (official API, server reads every page): optional status filter, sortBy (cpa|ctr|spent|views|cpm|clicks|actions; ads without the metric go last) and order, limit (default 40). Returns countsByStatus for the whole account plus compact rows: adId, title, status, cpmBid, budget, spent, dailyBudgetLimit, views, clicks, actions, ctr %, effective cpm, cpa, target. Never page; one call answers "which ads are active / best / worst". Telegram Ads (ads.telegram.org): text <=160 chars with at most one @username or t.me link; the URL makes the button (Telegram sets its label). CPM (min 0.1) and budgets are in TON, never converted. Live changes happen only after the owner confirms them in /telegram-ads; write tools return a review link. Never invent a URL, channel, ad id or number.
  • telegram_ads_remote_ad_stats: Live daily statistics of one Telegram ad (official API getAdStats, last N days, default 30): views, clicks, actions (as joins), spent. Also stored for the stats tab. Telegram Ads (ads.telegram.org): text <=160 chars with at most one @username or t.me link; the URL makes the button (Telegram sets its label). CPM (min 0.1) and budgets are in TON, never converted. Live changes happen only after the owner confirms them in /telegram-ads; write tools return a review link. Never invent a URL, channel, ad id or number.
  • telegram_ads_remote_ad_status: Request pausing or resuming a live Telegram ad. Never executed by this tool: returns a review link to /telegram-ads where the owner sees old -> new values and confirms. Telegram Ads (ads.telegram.org): text <=160 chars with at most one @username or t.me link; the URL makes the button (Telegram sets its label). CPM (min 0.1) and budgets are in TON, never converted. Live changes happen only after the owner confirms them in /telegram-ads; write tools return a review link. Never invent a URL, channel, ad id or number.
  • telegram_ads_remote_ad_edit: Request a CPM, daily budget limit or text/title/URL change on a live Telegram ad (text passes the policy check first). Never executed by this tool: returns a review link to /telegram-ads where the owner sees old -> new values and confirms. Telegram Ads (ads.telegram.org): text <=160 chars with at most one @username or t.me link; the URL makes the button (Telegram sets its label). CPM (min 0.1) and budgets are in TON, never converted. Live changes happen only after the owner confirms them in /telegram-ads; write tools return a review link. Never invent a URL, channel, ad id or number.
  • telegram_ads_remote_ad_create: Request creating a live Telegram ad from a saved draft (created paused with no budget). Never executed by this tool: returns a review link to /telegram-ads where the owner sees old -> new values and confirms. Telegram Ads (ads.telegram.org): text <=160 chars with at most one @username or t.me link; the URL makes the button (Telegram sets its label). CPM (min 0.1) and budgets are in TON, never converted. Live changes happen only after the owner confirms them in /telegram-ads; write tools return a review link. Never invent a URL, channel, ad id or number.
  • telegram_ads_remote_ad_submit: Request submitting a ready_for_review Telegram ad for moderation. Never executed by this tool: returns a review link to /telegram-ads where the owner sees old -> new values and confirms. Telegram Ads (ads.telegram.org): text <=160 chars with at most one @username or t.me link; the URL makes the button (Telegram sets its label). CPM (min 0.1) and budgets are in TON, never converted. Live changes happen only after the owner confirms them in /telegram-ads; write tools return a review link. Never invent a URL, channel, ad id or number.
  • telegram_ads_remote_ad_delete: Request deleting a Telegram ad (must be inactive 10+ minutes). Never executed by this tool: returns a review link to /telegram-ads where the owner sees old -> new values and confirms. Telegram Ads (ads.telegram.org): text <=160 chars with at most one @username or t.me link; the URL makes the button (Telegram sets its label). CPM (min 0.1) and budgets are in TON, never converted. Live changes happen only after the owner confirms them in /telegram-ads; write tools return a review link. Never invent a URL, channel, ad id or number.
  • telegram_ads_remote_ad_budget: Request moving money into (increase) or out of (decrease) a Telegram ad budget; capped per call. Never executed by this tool: returns a review link to /telegram-ads where the owner sees old -> new values and confirms. Telegram Ads (ads.telegram.org): text <=160 chars with at most one @username or t.me link; the URL makes the button (Telegram sets its label). CPM (min 0.1) and budgets are in TON, never converted. Live changes happen only after the owner confirms them in /telegram-ads; write tools return a review link. Never invent a URL, channel, ad id or number.

02

How changes stay safe

  • Two scopes, chosen by you at sign-in: read, and propose. With read alone the assistant cannot request any change.
  • A change requested from an assistant is a proposal. It waits in Approvals in Valkiria until the account owner approves it, unless the write policy you set for that account allows that kind of change by itself.
  • New campaigns are created paused. Starting new spend and deleting always wait for a person.
  • The assistant can list what is waiting for approval and reject a proposal. It cannot approve one: approval stays with the owner in Valkiria.
  • The change history shows who or what made each change and the value before and after, with Undo where the change can be reversed.
  • You can disconnect an assistant at any time on the Connect AI page; a developer API key can be deleted the same way.

03

Limits

  • The assistant sees only your own Valkiria workspace, and only the ad accounts connected there.
  • Numbers are as fresh as the last sync or import; the assistant can tell you when that was.
  • Money stays in each account's own currency. Different currencies are not converted or added up.
  • Reading data is not counted against the monthly allowance; changes and AI generations are. Allowances per plan are on the pricing page.

04

FAQ

Connect an assistant and call the first tool

Create a free account, connect an ad account and add the connector. The first pass only reads.

Drag to move. Alt + arrow keys move the button; Alt + Home resets its position.

Cookie Preferences

We use cookies to enhance your experience. Essential cookies are always active. You can manage optional cookies below.

Essential
Analytics
Marketing
Third-Party