telegram-ads-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| stel_ssid | Yes | The stel_ssid cookie from ads.telegram.org | |
| stel_token | Yes | The stel_token cookie from ads.telegram.org |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| check_sessionA | Ping the ads.telegram.org session. Use first in every chat; on ok=false code=auth offer INSTALL.md DevTools steps, then |
| check_updateA | 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. |
| reload_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. |
| list_accountsA | List ad cabinets for this Telegram login. Use to find owner_id before |
| select_accountA | Switch the active ad cabinet by owner_id from |
| get_accountA | Read the current cabinet card. Use before any write to check currency and gate; for the ad list use |
| get_adsA | List ads, 100 per page, status=any|active|on_hold. Use for account overviews; for one ad use |
| get_adA | Fetch one ad by id with full fields. Use for diagnosis; for metrics use |
| create_adA | Create an ad on_hold with the full targeting field set. Prefer |
| edit_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 |
| delete_adA | 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 |
| clone_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. |
| check_ad_postA | Validate promote_url and text before create or launch. Use before |
| send_target_to_reviewA | Submit or resubmit an ad's targeting for moderation. Use after edits; |
| launch_adA | Create on_hold, add budget (default 1 Gram), send to review; never activates. Use for new ads; full targeting via |
| preview_adA | 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. |
| upload_mediaA | Upload a photo (16:9, <5 MB) or video (MP4 3-60s, <20 MB) by file_path or media_base64. Use before |
| get_ad_statsA | 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 |
| search_targetsA | 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. |
| get_targeting_referenceA | List countries, languages, topics and channel taxonomies with IDs. Use for user-geo and topic targeting; for channels/bots use |
| manage_audienceA | 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. |
| manage_eventB | 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. |
| manage_fundsA | 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. |
| revoke_tokenA | 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. |
| save_api_settingsB | Set the newline-separated IP whitelist for the cabinet API token. Destructive; use only when the user asks. confirm=true unless gate=open. |
| log_outA | 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. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| launch-campaign | End-to-end flow to create and submit a Telegram ad. |
| review-account | Read-only morning pass: balance, live vs stopped ads, stats on a few problems. |
| diagnose-ad | Inspect one ad: card, stats, preview. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| playbook_resource | Full agent playbook (AGENTS.md). Prefer ads://guide/{topic} for one section. |
| guide_index_resource | List of guide topics: auth, write-gate, errors, stats, create, danger, ... |
| account_resource | Current cabinet: owner_id, currency, balance, type. |
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.