Skip to main content
Glama
telegram-ads-mcp

telegram-ads-mcp

by Free-cat

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 safe confirm=False dry-run and only take effect when an agent explicitly passes confirm=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

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-auth

telegram-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 chromium

Run 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

confirm required?

Description

list_accounts

Read

—

List Telegram Ads accounts available for this login session

list_ads

Read

—

List all ads with full table columns (id, metrics, budget, status, date)

get_ad_info

Read

—

Read ad form fields (targeting chips are read-only for existing ads)

get_account_budget

Read

—

Read-only per-ad budgets on /account/budget

update_ad

Write

Yes (to save)

Update ad info fields (title, text, url, budget, etc.), not CPM/budget delta

set_cpm

Write

Yes (to execute)

Set CPM via the /edit_cpm modal

set_status

Write

Yes (to execute)

Set ad status (Active / On Hold) via the /edit_status modal

increase_budget

Write (financial)

Yes (to execute)

Add TON to an ad's budget (delta)

set_budget

Write (financial)

Yes (to execute)

Set a target budget by computing the delta from the current one

create_ad

Write (financial)

Yes (to execute)

Create a new ad; clears the draft by default

get_ad_stats_csv

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

TELEGRAM_ADS_AUTH_STATE

Absolute path to the saved Playwright session file. Overrides the default lookup (~/.config/telegram-ads-mcp/auth_state.json, falling back to ./auth_state.json in the current directory).

TELEGRAM_ADS_ACCOUNT

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_info can read targeting chips, but changing targeting for an already-created ad is not supported — targeting is set at creation time via create_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

MIT

Available Tools

11 tools
create_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_budgetA
Read-only

Read-only: per-ad budgets on /account/budget. Fragment top-up is manual.

Inputs: no named parameters.

get_ad_infoC
Read-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_budgetA
Destructive

Add TON to ad budget (delta). Financial — requires confirm=True to execute; default is dry-run.

Inputs: ad_id (required), amount (required), confirm.

list_accountsA
Read-only

List Telegram Ads accounts available for this login session.

Inputs: no named parameters. Returns: result

list_adsA
Read-only

List all ads with full table columns (id, metrics, budget, status, date).

Inputs: no named parameters. Returns: result

set_budgetA
Destructive

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

    A3.8/5.0

    Scored across 11 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    With 11 tools, the set covers essential CRUD and management operations for Telegram Ads without being excessive or insufficient for the domain.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      MCP 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 npm
      6
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      A 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.
      13
      Apache 2.0