ads-telegram-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| TELEGRAM_ADS_TOKEN | Yes | API token for accessing Telegram Ads. Required for data requests. | |
| TELEGRAM_ADS_ACCOUNT_ID | No | Optional ID of the related account to use by default. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Telegram Ads tools for reading data, creating ads and uploading media. create_ads writes data unless dry_run=true; upload_media sends a local file. Creation may transfer budget, trigger review and enable delivery. Preserve per-ad idempotency keys when retrying within 24 hours.
Account IDs are strings; ad IDs are integers scoped to an account.
Omitted account_id uses TELEGRAM_ADS_ACCOUNT_ID if set, otherwise the token owner. get_current_account always returns the token owner.
Times are Unix seconds; end times are exclusive. Preserve currency.
List tools fetch one page; follow offsets explicitly.
Use get_ads_stats for per-ad period totals: empty ad_ids selects all ads with automatic paging. Check complete and errors for partial failures.
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 |
|---|---|
| get_current_accountA | Get the token owner's account, balances and currency. Always returns the token owner, regardless of the default related account. |
| list_related_accountsA | Get one page of the token owner's related accounts. Returns total_count and up to limit accounts. For the next page, increase the numeric offset by the number of accounts returned. |
| get_accounts_by_idA | Get balances and currencies for the specified account IDs. Accepts 1 to 100 IDs of accounts accessible to this token. Uses account_ids directly, regardless of the default related account. |
| create_adsA | Create one or more ads in order, or validate them locally with dry_run. Defaults are zero initial budget and paused delivery. Positive budget transfers account funds and may trigger review. Activation/deactivation dates override is_paused. Amounts use the selected account's currency. Each ad requires an idempotency_key. Retry with the same key and identical parameters within 24 hours; later retries may create another ad. Duplicates are not removed. No rollback is performed. Outcomes are succeeded, failed, unknown, or not_attempted. For unknown outcomes retry with the original key. stop_on_error defaults to true; authentication, permission and rate-limit errors always stop the batch. Unexpected client failures also stop remaining writes. dry_run makes no API calls and does not check access, budget or moderation. Omitted account_id uses the configured default or the token owner. |
| list_adsA | Get one page of ads from an account. For the next page, pass the returned next_offset unchanged as offset. This tool does not load additional pages automatically. Set return_target to include targeting settings. Omitted account_id uses TELEGRAM_ADS_ACCOUNT_ID if set, otherwise the token owner's account. |
| get_ads_by_idA | Get selected ads by their IDs. Accepts 1 to 100 IDs. Ad IDs are unique within an account. Set return_target to include targeting settings. Omitted account_id uses TELEGRAM_ADS_ACCOUNT_ID if set, otherwise the token owner's account. |
| get_ads_statsA | Get per-ad totals for [from_time, to_time), in Unix seconds. The period must not exceed 1000 intervals. Empty or omitted ad_ids selects all ads via automatic paging, regardless of status. Provided ad_ids are used as supplied. Set include_timeseries to include interval rows. Returns rounded bounds, per-ad totals, counts, complete and errors. Totals are null when no data is available. Check complete and errors before treating the result as complete. Omitted account_id uses TELEGRAM_ADS_ACCOUNT_ID if set, otherwise the token owner's account. |
| get_account_statsA | Get account statistics for [from_time, to_time), in Unix seconds. Returns a time series in intervals of 300 or 86400 seconds. The API rounds bounds to interval starts; at most 1000 intervals are allowed. Monetary values use the returned currency. Omitted account_id uses TELEGRAM_ADS_ACCOUNT_ID if set, otherwise the token owner's account. |
| get_ad_statsA | Get one ad's statistics for [from_time, to_time), in Unix seconds. Returns a time series in intervals of 300 or 86400 seconds. The API rounds bounds to interval starts; at most 1000 intervals are allowed. The ad ID is scoped to the selected account. Omitted account_id uses TELEGRAM_ADS_ACCOUNT_ID if set, otherwise the token owner's account. |
| get_account_reportA | Get per-ad totals for a calendar month. Returns a report of active ads for the given year and month. Monetary values use each item's currency. Omitted account_id uses TELEGRAM_ADS_ACCOUNT_ID if set, otherwise the token owner's account. |
| upload_mediaA | Upload a local photo, MP4 video, or website photo to Telegram Ads. file_path must be an absolute path on the server machine. The file's bytes are transmitted to Telegram. Images are checked with Pillow; video metadata validation requires ffprobe from FFmpeg on PATH. Returns account_id, kind, photo_id/photo_url or video_id/video_url, and validated media metadata. Reuse the ID only in the same account. Upload retries may create a new media ID; no idempotency key is available. Omitted account_id uses the configured default or the token owner. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 11 tools
Account tools (current, related, by-id) and ad tools (create, list, by-id) have clearly distinct purposes. The stats family is mostly separable, though get_ads_stats (per-ad totals for an arbitrary window) and get_account_report (per-ad totals for a calendar month) overlap in intent, and get_ads_stats vs get_ad_stats differ only by plural and require reading descriptions to distinguish.
Names follow a consistent snake_case verb_noun convention (get_*, list_*, create_*, upload_*). The singular/plural shifts (get_ad_stats vs get_ads_stats, get_accounts_by_id vs get_current_account) are semantically meaningful but make the surface slightly less predictable at a glance.
Eleven tools is well within a comfortable range for a domain covering accounts, ads, stats, reporting, and media. Each tool maps to a distinct resource/action, so none feels redundant padding.
Read and create paths are solid (accounts, ad listing, ad creation, several stats views, media upload), but there is no update/pause/delete or edit operation for ads, so the lifecycle dead-ends after creation. Targeting appears only as a read flag (return_target), with no way to modify it, which will force agents into workarounds.