Skip to main content
Glama
zai-one

telegram-ads-mcp

by zai-one
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
stel_ssidYesThe stel_ssid cookie from ads.telegram.org
stel_tokenYesThe 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

CapabilityDetails
tools
{
  "listChanged": false
}
prompts
{
  "listChanged": false
}
resources
{
  "subscribe": false,
  "listChanged": false
}
experimental
{}

Tools

Functions exposed to the LLM to take actions

NameDescription
check_sessionA

Ping the current ads.telegram.org session.

Returns owner_id, cabinet (ton/eur/stars), currency, balance.
Does not return api_hash or cookies. Stars cabinets are reported but not used.
If ok=false with code=auth, offer INSTALL.md DevTools steps; they write .env (never paste into chat); then reload_session.
reload_sessionA

Re-read .env (STEL_TOKEN / STEL_SSID / STEL_ADOWNER) and rebuild the HTTP session.

Use this after the user updates cookies on disk. Never pass cookie values as arguments.
list_accountsA

List ad cabinets for this Telegram login. Works even on a Stars cabinet so you can switch away.

select_accountA

Switch the active ad cabinet. Then check_session / get_account.

Args:
    owner_id: From list_accounts.
    confirm: Required when TG_ADS_WRITE_GATE=strict.
get_accountA

Current cabinet card: owner_id, cabinet (ton/eur/stars), currency (GRAM/EUR), balance, write_gate.

get_adsA

List ads (100 per page). Filter by status client-side.

Args:
    offset_id: Pagination cursor from next_offset_id.
    status: any | active | on_hold.
get_adA

Fetch a single ad by id (API method, HTML state, or list fallback).

create_adA

Create an ad. TON/Gram cabinets allow channels, bots, search, and users (geo). EUR too.

Always create on_hold. Budget "0" cannot go to review. IDs are semicolon-separated.
Search ads: do not pass text/picture/media.
Empty strings are stripped and not sent.
Do not send langs together with specific channel IDs (platform Target invalid) —
langs is dropped in that case.
confirm: required for spend (budget>0 or active) when TG_ADS_WRITE_GATE is not open.
edit_adA

Edit an ad. Only provided fields are sent.

picture=True shows the avatar, picture=False turns it off (sends picture=0).
clear_media=True removes attached photo/video.
budget_action + budget_amount changes total budget (increase resumes a depleted Stopped ad).
Targeting cannot be changed after creation — clone_ad instead.
confirm: required to activate or change budget unless TG_ADS_WRITE_GATE=open.
delete_adA

Delete an ad. Two-step: first call without confirm_hash; pass the returned hash to confirm.

confirm: TG_ADS_WRITE_GATE (danger). confirm_hash is the platform hash, not the gate.
clone_adA

Duplicate an ad into a new draft. Targeting is copied; edit the clone if you need changes.

Two-step confirm_hash (platform). confirm is TG_ADS_WRITE_GATE (write).
check_ad_postA

Validate promote URL + text before create/launch. Surfaces platform errors.

send_target_to_reviewB

Submit (or resubmit) targeting for review. Requires a non-zero budget. Spend-class gate.

launch_adA

Create on_hold, add budget, submit for review. Does not activate.

Spends `budget` (default 1 Gram) and sends targeting to review. Not go-live.
Returns each step so you can see which one failed. Prefer this over calling
create_ad + edit_ad + send_target_to_review by hand.
Safe targeting subset vs create_ad: topics, exclude_*, locations, user_langs/user_topics.
Do not send langs together with specific channel IDs (platform Target invalid);
langs is dropped in that case. Full field set remains on create_ad.
confirm: required unless TG_ADS_WRITE_GATE=open.
preview_adB

Render a sponsored-message preview PNG for chat, and save it under TG_ADS_PREVIEW_DIR (default ./previews).

upload_mediaA

Upload a photo (JPEG/PNG 16:9, <5 MB) or video (MP4 3–60s, <20 MB).

Pass a local file_path OR media_base64 (+ filename). Returns a media hash
to feed into create_ad(media=...) / edit_ad(media=...).
get_ad_statsA

Time-bucketed stats plus CTR / CPC / actual CPM.

period=5min → last 24h in 5-minute buckets. period=day → full lifetime daily.
Success JSON echoes the request `period` (`5min`/`day`). `summary.period` is a
span label (`24h`/`Nd`), not the request arg.
`summary.spend` is already scaled (Gram on a TON cabinet); `spend_already_scaled`
is true; `spend_scale` stays for compatibility. Do not divide again.
`charts.budget` series/totals are scaled the same way (`values_already_scaled`).
Prefer `summary.spend`. No CSV tool — if you save a file, gitignored `reports/`.
search_targetsA

Search targeting entities.

kind=channel|bot|query|location, or similar_channels/similar_bots (pass ids as semicolon-separated).
purpose=target (placement) vs promote (destination URL lookup). Bots use field=bots vs promote_url.
get_targeting_referenceA

Countries / languages / topics for user-geo (Gram cabinets have this too) plus channel taxonomies.

Stars cabinets never reach this tool. Empty lists mean the form did not embed that taxonomy.

manage_audienceB

Custom audiences. action=list|create|rename|delete|clone.

create: pass file_path (one user id per line) or user_ids=[...].
delete/clone: two-step confirm_hash (platform). confirm is TG_ADS_WRITE_GATE.
list is not gated. Access denied → code:access_denied, hint:skip (do not retry).
manage_eventC

Conversion events and pixels. action=list|create|rename|delete|create_pixel.

list is not gated. delete is danger + two-step confirm_hash.
Access denied → code:access_denied, hint:skip (do not retry).
manage_fundsA

Funds. Amount is a Gram (or EUR) string.

list/search = lookup, not gated.
add = top-up *request* (not instant credit).
transfer/withdraw = money moves in this one call — no confirm_hash. Danger gate.
revoke_tokenA

Revoke and regenerate the cabinet API token (IP-whitelist token, not ads cookies).

save_api_settingsA

Set the IP whitelist for the cabinet API token. Newline-separated IPs.

log_outA

Log out of ads.telegram.org for this session. You will need fresh cookies in .env afterwards.

Prompts

Interactive templates invoked by user choice

NameDescription
launch-campaignEnd-to-end flow to create and submit a Telegram ad.
review-accountRead-only morning pass: balance, live vs stopped ads, stats on a few problems.
diagnose-adInspect one ad: card, stats, preview.

Resources

Contextual data attached and managed by the client

NameDescription
playbook_resourceAgent playbook: auth, create-on-hold, budget, review, Gram.
account_resourceCurrent cabinet: owner_id, currency, balance, type.
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored across 25 tools

Disambiguation4/5

Most tools clearly target a distinct resource or action, and the get/create/edit/delete/launch/clone ad family is well-separated. A few pairs could confuse agents, notably check_session vs. get_account (both return account/session state) and create_ad vs. launch_ad vs. send_target_to_review (atomic vs. composite paths), though descriptions reduce ambiguity.

Naming Consistency5/5

Tool names overwhelmingly follow a consistent verb_noun pattern (get_ads, create_ad, edit_ad, delete_ad, clone_ad, upload_media). The manage_audience/manage_event/manage_funds umbrella names are predictable, and minor variants like log_out or check_ad_post do not disrupt the overall convention.

Tool Count3/5

At 25 tools, this sits at the heavy end of the 16–25 borderline range. The broad Telegram Ads domain justifies much of the surface, but some session/account tools and wrapper workflows could be consolidated into fewer, higher-level tools.

Completeness5/5

The surface comprehensively covers auth and session management, account switching, the full ad lifecycle (create, read, update, delete, clone, launch, review, stats), media upload, targeting, audiences, events, and funds. There are no obvious dead ends for the stated domain.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources