telegram-ads-mcp
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 list my ads"
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.
telegram-ads-mcp
An MCP server that lets AI agents (Cursor, Claude Desktop, etc.) read and manage your Telegram Ads campaigns — list accounts and ads, read stats and budgets, and create/update ads, CPM, status, and budget — by driving the real ads.telegram.org web UI through Playwright with a reused, cookie-based login session.
⚠️ Security warning
This server reuses a saved Telegram Ads browser session (
auth_state.json). That file is equivalent to your login credentials for ads.telegram.org — anyone with it can act as you, including spending your TON ad budget. Never commit it, share it, or check it into version control. Mutating and financial tools (update_ad,set_cpm,set_status,increase_budget,set_budget,create_ad,get_ad_stats_csv) default to a safeconfirm=Falsedry-run and only take effect when an agent explicitly passesconfirm=True. Read SECURITY.md before connecting this server to any agent you don't fully trust with your ad spend.
Requirements
Python 3.11+
Chromium, installed via Playwright (
playwright install chromium)A Telegram Ads account with access to ads.telegram.org
Related MCP server: OpenAI Ads MCP Server
Quick start (recommended: clone)
Cloning and installing in a virtualenv is the recommended path — it makes the one-time interactive login step and the Playwright browser install straightforward and reproducible.
git clone https://github.com/Free-cat/telegram_ads_mcp.git
cd telegram_ads_mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
playwright install chromium
telegram-ads-authtelegram-ads-auth opens a real (visible) browser window so you can log in
to Telegram, choose the ads account you want to manage, and save the session.
It prints the path it saved to (by default
~/.config/telegram-ads-mcp/auth_state.json).
Cursor configuration
Add the server to your mcp.json, using the absolute path to the console
script inside the venv you just created:
{
"mcpServers": {
"telegram-ads": {
"command": "/ABS/PATH/telegram_ads_mcp/.venv/bin/telegram-ads-mcp",
"env": {
"TELEGRAM_ADS_ACCOUNT": "Artem",
"TELEGRAM_ADS_AUTH_STATE": "/ABS/PATH/to/auth_state.json"
}
}
}
}Restart Cursor (or reload MCP servers) after adding this. The same shape
works for Claude Desktop's claude_desktop_config.json.
Alternative: install via pip + git
If you'd rather not clone, you can install directly from git:
pip install "git+https://github.com/Free-cat/telegram_ads_mcp.git"
playwright install chromiumRun playwright install chromium in the same environment/interpreter
you installed the package into, so the browser binary is available at
runtime. Ephemeral environments (e.g. running via uvx on every invocation)
are fragile for this reason — Playwright needs its browser binaries to
persist between runs — which is why the clone + venv path above is
recommended for anything beyond a quick try.
Tools
All mutating/financial tools default to confirm=False, which returns a
structured dry-run preview and makes no changes. Pass confirm=True to
actually execute the action.
Tool | Type |
| Description |
| Read | — | List Telegram Ads accounts available for this login session |
| Read | — | List all ads with full table columns (id, metrics, budget, status, date) |
| Read | — | Read ad form fields (targeting chips are read-only for existing ads) |
| Read | — | Read-only per-ad budgets on |
| Write | Yes (to save) | Update ad info fields (title, text, url, budget, etc.), not CPM/budget delta |
| Write | Yes (to execute) | Set CPM via the |
| Write | Yes (to execute) | Set ad status (Active / On Hold) via the |
| Write (financial) | Yes (to execute) | Add TON to an ad's budget (delta) |
| Write (financial) | Yes (to execute) | Set a target budget by computing the delta from the current one |
| Write (financial) | Yes (to execute) | Create a new ad; clears the draft by default |
| Write (download) | Yes (to execute) | Download the stats CSV for an ad and period |
Every tool raises a stable AUTH_EXPIRED error when the stored session is no
longer valid — re-run telegram-ads-auth to refresh it.
Configuration
Env var | Purpose |
| Absolute path to the saved Playwright session file. Overrides the default lookup ( |
| Substring match against the account name shown on the Telegram Ads "Choose Account" screen, used to select which account's ads the tools operate on. Optional when your login has exactly one account; required when multiple accounts are available. |
Limitations
Fragment top-ups are manual. The server can read per-ad budgets but does not automate adding TON via Fragment.
Ad Schedule and similar widgets are not automated. Scheduling and "Similar channels/bots" targeting widgets on ads.telegram.org are out of scope for v0.1.
Targeting on existing ads is read-only.
get_ad_infocan read targeting chips, but changing targeting for an already-created ad is not supported — targeting is set at creation time viacreate_ad.No live end-to-end tests in CI. Tests that hit the real ads.telegram.org are marked
live, require a real session, and are never run automatically — they need a human with an active account to run them locally.Transport is stdio only. There is no remote/HTTP transport or Docker image in this release.
License
Available Tools
11 toolscreate_adB
Create new ad. Financial — requires confirm=True. Clears draft by default.
Inputs: cpm (required), url (required), text (required), title (required), +9 more.
get_account_budgetARead-only
Read-only: per-ad budgets on /account/budget. Fragment top-up is manual.
Inputs: no named parameters.
get_ad_infoCRead-only
Read ad form fields. Targeting chips are read-only for existing ads.
Inputs: ad_id (required).
get_ad_stats_csvB
Download stats CSV. Requires confirm=True to actually download; default is dry-run.
Inputs: ad_id (required), period, confirm. Returns: result
increase_budgetADestructive
Add TON to ad budget (delta). Financial — requires confirm=True to execute; default is dry-run.
Inputs: ad_id (required), amount (required), confirm.
list_accountsARead-only
List Telegram Ads accounts available for this login session.
Inputs: no named parameters. Returns: result
list_adsARead-only
List all ads with full table columns (id, metrics, budget, status, date).
Inputs: no named parameters. Returns: result
set_budgetADestructive
Set target budget by computing delta from current. Financial — requires confirm=True to execute; default is dry-run.
Inputs: ad_id (required), target_budget (required), confirm.
set_cpmA
Set CPM via /edit_cpm modal. Requires confirm=True to execute; default is dry-run.
Inputs: cpm (required), ad_id (required), confirm.
set_statusA
Set ad status (Active / On Hold) via /edit_status modal. Requires confirm=True to execute; default is dry-run.
Inputs: ad_id (required), status (required), confirm.
update_adA
Update ad info fields (not CPM/budget). Requires confirm=True to save; default is dry-run.
Inputs: ad_id (required), url, text, title, +6 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool has a clear, distinct purpose. Operations like set_budget and increase_budget handle different budget manipulations, and other tools cover creation, reading, listing, and updating without overlap.
All tool names follow a consistent snake_case verb_noun pattern (e.g., create_ad, list_accounts, set_cpm), making the set predictable and easy to navigate.
With 11 tools, the set covers essential CRUD and management operations for Telegram Ads without being excessive or insufficient for the domain.
Core operations are present: create, read (info, stats, list), update (fields, budget, CPM, status). However, a delete ad tool is missing, which is a minor gap for full lifecycle management.
Maintenance
Related MCP Connectors
Hosted X Ads MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Hosted Telegram MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Google Ads MCP server: run Search, Display, Demand Gen and PMax campaigns from AI.
X Ads (Twitter Ads) MCP server: run X campaigns, ad groups, ads and reports from AI.
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server for AI agents to manage ad campaigns across Google, Meta, LinkedIn, Microsoft, Reddit, TikTok, and more21210 npm21MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that exposes the ChatGPT Ads API as tools an LLM host can call.4MIT
- AlicenseNot gradedqualityAmaintenanceMCP server for VK Ads API (myTarget v2) that allows AI agents to manage advertising accounts: create and modify campaigns, ads, upload creatives, and fetch statistics.145 npm6Apache 2.0
- AlicenseNot gradedqualityBmaintenanceA safe-by-default MCP server for real Telegram accounts powered by TDLib, enabling AI agents to read and act on your account with read-only mode and human approval for destructive actions.13Apache 2.0