Telegram Ads

zai-one4stars

MCP server for Telegram Ads (ads.telegram.org, TON): create, target, pause ads and read stats; 26 tools, ads start on hold, write gate, prompts; optional lazy tool loading.

Communication

Install Run on PlugMCP

GitHub Website

Run on PlugMCP

1# Telegram Ads

README.mdMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

Install from the publisher. Not a PlugMCP endpoint.

Run on PlugMCP

Host a copy with our keys and logs.

No packaged release in the registry yet. Follow the repository README.

RepositoryPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
License: NOASSERTION
Last checked: 2026-10-28

Stars: 4
Tools: —
Uptime: —

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install Telegram Ads?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Telegram Ads need an API key?

No required environment variable is listed on this record.

What transport does Telegram Ads use?

Telegram Ads runs locally over stdio.

When was Telegram Ads last checked?

Last checked 2026-10-28. MCP server for Telegram Ads (ads.telegram.org, TON): create, target, pause ads and read stats; 26 tools, ads start on hold, write gate, prompts; optional lazy tool loading.

From the publisher

Documentation

MCP server for the Telegram Ads platform (ads.telegram.org, TON cabinet): create, target, pause and read stats for ads; 26 tools, new ads start on hold.

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 26 MCP tools, plus ads://playbook and ads://account.

Cabinets: TON (billed in Gram), EUR and Stars (whole-number amounts, no user targeting; opt-in with TG_ADS_STARS=on). get_account returns money rules; bad amounts are rejected before any call. Unofficial — not Telegram.

Write permission is .env TG_ADS_WRITE_GATE=strict|confirm|open (default confirm). Spend/destructive tools need confirm=true unless open. A blocked call returns code: write_gated with tool / class / would_send (intended args, no secrets) and sent: false — not a platform dry-run.

Why this MCP

Optional lazy tool loading: set TG_ADS_TOOL_LOADING=lazy (or choose it in the setup wizard) to start with a small core and enable toolsets on demand; see Lazy tool loading.
Money safety: ads are created on_hold; spending actions go through a write gate shown by get_account.
Targeting references and search_targets so the agent never guesses IDs; 3 prompts, 3 resources incl. ads://playbook.
Session cookies stay in .env, never in chat.
Other Telegram Ads MCP servers on GitHub: Free-cat/telegram_ads_mcp (14 tools), reputasyon/telegram-ads-mcp (8 tools).

Lazy tool loading

Optional lazy tool loading: TG_ADS_TOOL_LOADING=lazy starts with a small core plus tg_ads_enable_toolsets and adds toolsets on demand (tools/list_changed). Startup cost (tools/list + instructions, ≈chars/4): eager ≈7262 tokens, lazy ≈1748 tokens (−76%). Default eager is unchanged; if your client ignores tools/list_changed, keep eager or reconnect after enabling. Scope: enablement is process-wide (the MCP SDK MCPServer has no per-session tool visibility). Over stdio that is one client; in shared HTTP mode one client's enabled toolsets are listed for every client of that process (each call still passes its own gates), so use eager for shared HTTP.

Clients and notifications/tools/list_changed (verified against official docs, changelogs or maintainer statements, 2026-10):

Client	`tools/list_changed`	Source
Claude Code	Supported (interactive: tools, prompts, resources; `-p`/Agent SDK: tools)	docs: Dynamic tool updates
VS Code (GitHub Copilot)	Supported (dynamic tool discovery); new tools may reach the agent only on the next turn	docs, #303012
Gemini CLI	Supported (refreshes the tool registry)	PR #14375, PR #21050
Cursor	Unreliable: staff confirm a regression in 3.12.x; restart Cursor after enabling	forum
Claude Desktop, Windsurf, Codex CLI, Cline, Zed, Continue	Unverified: no official statement found; use `eager` or reconnect after enabling	—

Maintained and up to date

Actively maintained by ZAI.ONE: current version 0.6.0; release notes in CHANGELOG.md and Releases.
Built-in update check: ask the assistant to run check_update (public GitHub API, no credentials, cached; nothing is installed automatically; TG_ADS_DISABLE_UPDATE_CHECK=1 turns it off).
Follows current MCP practice: tool annotations (read-only / destructive hints), server instructions, prompts and resources, structured errors with recovery hints, secrets kept out of tool output, a token budget for tool descriptions enforced in tests.
CI runs the test suite on Linux and Windows for every pull request.

What's new in 0.5.0

Compact output. get_ads and get_ad_stats return detail="summary" by default: no null/empty fields, no per-bucket charts. Pass detail="full" for the previous payload.
Safer .env. From the working folder's .env only STEL_* cookies are read (no parent walk); settings come from TG_ADS_ENV_FILE, the clone's .env or the process environment.
Agent layer. Router instructions, skills (launch / review / diagnose), ads://guide/{topic}, error hint / docs, Claude Code and Cursor plugins pinned to v0.5.0.
License. LicenseRef-ZAI-ONE 2.0 (source-available); earlier MIT releases stay MIT (see NOTICE).

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 — DevTools steps in INSTALL.md; never paste into chat

{
  "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. Example: mcp.json.example.

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

Install anywhere (uvx, plugins)

Cookies stay in a .env file on disk (never in MCP env values or chat). For uvx installs point TG_ADS_ENV_FILE at that file (path only), or start the client from a folder that has .env. From the working folder's .env (that folder only, not its parents) the server takes STEL_* cookies and nothing else; settings such as TG_ADS_WRITE_GATE, MCP_TRANSPORT / MCP_HOST / MCP_PORT or TG_ADS_DISABLE_UPDATE_CHECK are read only from TG_ADS_ENV_FILE, the clone's own .env, or the process environment, so an unrelated project's .env cannot open the write gate or expose the server on the network.

# Claude Code: MCP only
claude mcp add telegram-ads --env TG_ADS_ENV_FILE=/path/to/telegram-ads.env -- uvx --from git+https://github.com/zai-one/[email protected] telegram-ads-mcp
# Claude Code: plugin = MCP + skills (launch / review / diagnose)
/plugin marketplace add zai-one/telegram-ads-mcp
/plugin install telegram-ads@telegram-ads-mcp

Cursor: one-click install or .cursor/mcp.json:

{"mcpServers": {"telegram-ads": {"command": "uvx", "args": ["--from", "git+https://github.com/zai-one/[email protected]", "telegram-ads-mcp"], "env": {"TG_ADS_ENV_FILE": "/path/to/telegram-ads.env"}}}}

Codex ~/.codex/config.toml:

[mcp_servers.telegram-ads]
command = "uvx"
args = ["--from", "git+https://github.com/zai-one/[email protected]", "telegram-ads-mcp"]
env = { TG_ADS_ENV_FILE = "/path/to/telegram-ads.env" }

Claude Desktop claude_desktop_config.json: the same mcpServers block as Cursor. Skills for Codex and other hosts: copy skills/* into .agents/skills/.

Skills: telegram-ads-launch-campaign, telegram-ads-review-account, telegram-ads-diagnose-ad (mirrored by the prompts). Guides on demand: ads://guide/index → ads://guide/{topic}.

Example asks: "Review my Telegram Ads cabinet", "Launch an ad for t.me/my_channel with CPM 0.5 and budget 5 Gram", "Why does ad 35 get no views?", "Pause ad 35", "Show stats for ad 35 for its lifetime".

Tools

Area	Tools
Auth	`check_session` `reload_session` `list_accounts` `select_account` `get_account`
Ads	`get_ads` `get_ad` `get_ad_stats` `create_ad` `edit_ad` `delete_ad` `clone_ad` `launch_ad` `check_ad_post` `send_target_to_review`
Creatives	`upload_media` `preview_ad`
Targeting	`search_targets` `get_targeting_reference`
Other	`manage_audience` `manage_event` `manage_funds` `save_api_settings` `revoke_token` `log_out`
Updates	`check_update`

Always create ads on_hold. budget="0" cannot go to review. Amounts are Gram strings. Search ads: no text / picture / media. launch_ad does not activate; it adds budget and sends review. Do not combine langs with specific channels.

Updates. check_update compares your version with the latest release and returns the release notes link plus the command to run (git pull --ff-only && uv sync in a clone, otherwise pip install --upgrade "telegram-ads-mcp @ git+…@vX"). run_in says where to run it. It only suggests and never installs. Only plain version tags (v1.2.3) are accepted. One anonymous GitHub API call, 3 s timeout, cached 24 h; after a failed call it waits 30 min, and force=true re-checks at most once a minute; offline returns status: unavailable. When the cache knows of a newer release, check_session adds update_hint and the server instructions get one line. At startup (stdio and HTTP alike) the server itself calls api.github.com anonymously, at most once a day, unless disabled; for a server or firewalled deployment set TG_ADS_DISABLE_UPDATE_CHECK=1 in .env or the process environment.

Issues

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

Use the form. Tick both “no cookies / no hashes” boxes. Never paste stel_token, stel_ssid, .env, confirm_hash, API hash=, or DevTools screenshots.

Local draft: uv run python scripts/check_security.py --issue draft.md — prints gh issue create only if the draft is clean. It does not open the Issue.

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

EUR and Stars support is fixture-tested; found a mismatch on a live EUR/Stars cabinet? Write on Telegram: t.me/zai_one. Do not send cookies in the GitHub issue.

Built by ZAI.ONE

ZAI.ONE is a digital agency working on websites, SEO, advertising and analytics. We also build tools that connect AI assistants to everyday work. Talk to us on Telegram about setup, automation or an integration for your team.

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

License, use and contributing

Use: you may install and use this MCP server freely for yourself and your organisation, including commercial work. If it helps, please consider giving the repository a ⭐ — appreciated, never required.
Contribute: issues and pull requests are welcome; see CONTRIBUTING.md. Never post tokens, cookies, sessions or account data.
Not allowed without written permission from ZAI.ONE: copying code into other projects, forking for redistribution, embedding the server in other products or offering it as a competing service.
License: LicenseRef-ZAI-ONE 2.0 (source-available, not open source). Third-party notices and license history: NOTICE.

Telegram Ads

zai-one4stars

MCP server for Telegram Ads (ads.telegram.org, TON): create, target, pause ads and read stats; 26 tools, ads start on hold, write gate, prompts; optional lazy tool loading.

Communication

Install Run on PlugMCP

GitHub Website

Run on PlugMCP

1# Telegram Ads

README.mdMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

Install from the publisher. Not a PlugMCP endpoint.

Run on PlugMCP

Host a copy with our keys and logs.

No packaged release in the registry yet. Follow the repository README.

RepositoryPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
License: NOASSERTION
Last checked: 2026-10-28

Stars: 4
Tools: —
Uptime: —

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install Telegram Ads?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Telegram Ads need an API key?

No required environment variable is listed on this record.

What transport does Telegram Ads use?

Telegram Ads runs locally over stdio.

When was Telegram Ads last checked?

Last checked 2026-10-28. MCP server for Telegram Ads (ads.telegram.org, TON): create, target, pause ads and read stats; 26 tools, ads start on hold, write gate, prompts; optional lazy tool loading.

From the publisher

Documentation

MCP server for the Telegram Ads platform (ads.telegram.org, TON cabinet): create, target, pause and read stats for ads; 26 tools, new ads start on hold.

Why

Why this MCP

Optional lazy tool loading: set TG_ADS_TOOL_LOADING=lazy (or choose it in the setup wizard) to start with a small core and enable toolsets on demand; see Lazy tool loading.
Money safety: ads are created on_hold; spending actions go through a write gate shown by get_account.
Targeting references and search_targets so the agent never guesses IDs; 3 prompts, 3 resources incl. ads://playbook.
Session cookies stay in .env, never in chat.
Other Telegram Ads MCP servers on GitHub: Free-cat/telegram_ads_mcp (14 tools), reputasyon/telegram-ads-mcp (8 tools).

Lazy tool loading

Clients and notifications/tools/list_changed (verified against official docs, changelogs or maintainer statements, 2026-10):

Client	`tools/list_changed`	Source
Claude Code	Supported (interactive: tools, prompts, resources; `-p`/Agent SDK: tools)	docs: Dynamic tool updates
VS Code (GitHub Copilot)	Supported (dynamic tool discovery); new tools may reach the agent only on the next turn	docs, #303012
Gemini CLI	Supported (refreshes the tool registry)	PR #14375, PR #21050
Cursor	Unreliable: staff confirm a regression in 3.12.x; restart Cursor after enabling	forum
Claude Desktop, Windsurf, Codex CLI, Cline, Zed, Continue	Unverified: no official statement found; use `eager` or reconnect after enabling	—

Maintained and up to date

Actively maintained by ZAI.ONE: current version 0.6.0; release notes in CHANGELOG.md and Releases.
Built-in update check: ask the assistant to run check_update (public GitHub API, no credentials, cached; nothing is installed automatically; TG_ADS_DISABLE_UPDATE_CHECK=1 turns it off).
Follows current MCP practice: tool annotations (read-only / destructive hints), server instructions, prompts and resources, structured errors with recovery hints, secrets kept out of tool output, a token budget for tool descriptions enforced in tests.
CI runs the test suite on Linux and Windows for every pull request.

What's new in 0.5.0

Compact output. get_ads and get_ad_stats return detail="summary" by default: no null/empty fields, no per-bucket charts. Pass detail="full" for the previous payload.
Safer .env. From the working folder's .env only STEL_* cookies are read (no parent walk); settings come from TG_ADS_ENV_FILE, the clone's .env or the process environment.
Agent layer. Router instructions, skills (launch / review / diagnose), ads://guide/{topic}, error hint / docs, Claude Code and Cursor plugins pinned to v0.5.0.
License. LicenseRef-ZAI-ONE 2.0 (source-available); earlier MIT releases stay MIT (see NOTICE).

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 — DevTools steps in INSTALL.md; never paste into chat

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

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

Install anywhere (uvx, plugins)

# Claude Code: MCP only
claude mcp add telegram-ads --env TG_ADS_ENV_FILE=/path/to/telegram-ads.env -- uvx --from git+https://github.com/zai-one/[email protected] telegram-ads-mcp
# Claude Code: plugin = MCP + skills (launch / review / diagnose)
/plugin marketplace add zai-one/telegram-ads-mcp
/plugin install telegram-ads@telegram-ads-mcp

Cursor: one-click install or .cursor/mcp.json:

{"mcpServers": {"telegram-ads": {"command": "uvx", "args": ["--from", "git+https://github.com/zai-one/[email protected]", "telegram-ads-mcp"], "env": {"TG_ADS_ENV_FILE": "/path/to/telegram-ads.env"}}}}

Codex ~/.codex/config.toml:

[mcp_servers.telegram-ads]
command = "uvx"
args = ["--from", "git+https://github.com/zai-one/[email protected]", "telegram-ads-mcp"]
env = { TG_ADS_ENV_FILE = "/path/to/telegram-ads.env" }

Claude Desktop claude_desktop_config.json: the same mcpServers block as Cursor. Skills for Codex and other hosts: copy skills/* into .agents/skills/.

Skills: telegram-ads-launch-campaign, telegram-ads-review-account, telegram-ads-diagnose-ad (mirrored by the prompts). Guides on demand: ads://guide/index → ads://guide/{topic}.

Tools

Area	Tools
Auth	`check_session` `reload_session` `list_accounts` `select_account` `get_account`
Ads	`get_ads` `get_ad` `get_ad_stats` `create_ad` `edit_ad` `delete_ad` `clone_ad` `launch_ad` `check_ad_post` `send_target_to_review`
Creatives	`upload_media` `preview_ad`
Targeting	`search_targets` `get_targeting_reference`
Other	`manage_audience` `manage_event` `manage_funds` `save_api_settings` `revoke_token` `log_out`
Updates	`check_update`

Issues

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

Use the form. Tick both “no cookies / no hashes” boxes. Never paste stel_token, stel_ssid, .env, confirm_hash, API hash=, or DevTools screenshots.

Local draft: uv run python scripts/check_security.py --issue draft.md — prints gh issue create only if the draft is clean. It does not open the Issue.

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

EUR and Stars support is fixture-tested; found a mismatch on a live EUR/Stars cabinet? Write on Telegram: t.me/zai_one. Do not send cookies in the GitHub issue.

Built by ZAI.ONE

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

License, use and contributing

Use: you may install and use this MCP server freely for yourself and your organisation, including commercial work. If it helps, please consider giving the repository a ⭐ — appreciated, never required.
Contribute: issues and pull requests are welcome; see CONTRIBUTING.md. Never post tokens, cookies, sessions or account data.
Not allowed without written permission from ZAI.ONE: copying code into other projects, forking for redistribution, embedding the server in other products or offering it as a competing service.
License: LicenseRef-ZAI-ONE 2.0 (source-available, not open source). Third-party notices and license history: NOTICE.