telegram-ads-mcp

Why

Telegram does not publish an advertiser API. This server wraps the logged-in ads.telegram.org session (stel_token / stel_ssid in a gitignored .env) and exposes ~25 MCP tools, plus ads://playbook and ads://account.

Live cabinet unit is Gram. User-geo (target_type=users) works. Stars cabinets are refused (code: stars_cabinet). Unofficial — not Telegram.

Related MCP server: adkit

Quick start

git clone https://github.com/zai-one/telegram-ads-mcp.git
cd telegram-ads-mcp
uv sync
cp .env.example .env    # stel_token + stel_ssid from ads.telegram.org cookies

{
  "mcpServers": {
    "telegram-ads": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/telegram-ads-mcp", "run", "telegram-ads-mcp"]
    }
  }
}

Agent setup (clone, config, star): copy INSTALL.md into the chat. Command: telegram-ads-mcp (alias tg-ads-mcp). After connect: ads://playbook. Prompts: launch-campaign, review-account, diagnose-ad. Client file names are in INSTALL.md (Cursor, Claude, VS Code servers, Codex TOML). Do not put cookies in MCP env.

HTTP: uv run telegram-ads-mcp --transport streamable-http --host 127.0.0.1 --port 8000 → http://127.0.0.1:8000/mcp.

Tools

Always create ads on_hold. budget="0" cannot go to review. Amounts are Gram strings. Search ads: no text / picture / media.

Issues

I'm working on this. If something is missing or broken, open an issue. I will patch this repo.

Use the form. Tick “no cookies”. Never paste stel_token, stel_ssid, .env, hashes, or DevTools screenshots.

Support is not guaranteed. Issues are read when I can.

Need EUR or Stars cabinets (not live here)? Write on Telegram: t.me/zai_one. We can talk about access. Do not send cookies in the GitHub issue.

ZAI.ONE · contact@zai.one · Telegram

LicenseRef-ZAI-ONE · LICENSE · SECURITY.md · open an issue