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: mcp-telegram

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

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

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