Skip to main content
Glama
Telegram Ads MCP

Telegram Ads MCP

An open-source Model Context Protocol server for the official Telegram Ads API. Manage accounts, advertisements, budgets, statistics, audiences, pixels and targeting from Claude, Cursor, Codex, OpenCode or any MCP-compatible client.

  • Official API only. No cookies, browser automation or private endpoints.

  • Local-first. Runs over stdio on your machine. Your token never leaves it except to call promoteapi.telegram.org.

  • Safe by default. Read-only mode, explicit write confirmation, budget caps, idempotency keys and an optional JSONL audit log.

  • Built for agents. 24 focused tools, a searchable catalog of all 45 official methods, guided prompts, and an optional sandboxed Code Mode for multi-step work.

This project is unofficial and is not affiliated with, endorsed by or sponsored by Telegram. The Telegram name and logo are trademarks of their respective owners.

Contents

Related MCP server: telegram-ads-mcp

Quick start

Prerequisites

1. Connect the server

The package name is telegram-ads-mcp. Until the first npm release is available, install straight from GitHub; npm builds the package automatically:

npx -y github:furkankoykiran/telegram-ads-mcp doctor

After the npm release, the shorter form works too:

npx -y telegram-ads-mcp doctor

Or build a local checkout:

git clone https://github.com/furkankoykiran/telegram-ads-mcp.git
cd telegram-ads-mcp
npm install
node dist/cli.js doctor

doctor checks the token against the API and prints the account currency and budget. It is the fastest way to confirm everything works.

2. Write your client configuration

init writes the correct file for each client and keeps a .bak copy of an existing config:

npx -y telegram-ads-mcp init --client claude-desktop --token <your-token>
npx -y telegram-ads-mcp init --client cursor --token <your-token>
npx -y telegram-ads-mcp init --client opencode --token <your-token>
npx -y telegram-ads-mcp init --client all --token <your-token>

Before the npm release, add --github so the generated config launches the GitHub package instead:

npx -y github:furkankoykiran/telegram-ads-mcp init --client all --github --token <your-token>

For a local checkout, add --local . so the generated config launches node dist/cli.js instead of npx:

node dist/cli.js init --client claude-desktop --local . --token <your-token>

Prefer to edit files by hand? --print prints the merged configuration without writing anything. Claude Code and Codex are CLI-based; init prints the exact claude mcp add / codex mcp add command instead of editing their config.

{
  "mcpServers": {
    "telegram-ads": {
      "command": "npx",
      "args": ["-y", "telegram-ads-mcp"],
      "env": {
        "TELEGRAM_ADS_TOKEN": "your-token",
        "TG_ADS_MODE": "read-only",
        "TG_ADS_CODE_MODE": "read-only"
      }
    }
  }
}
{
  "mcp": {
    "servers": {
      "telegram-ads": {
        "type": "local",
        "command": ["npx", "-y", "telegram-ads-mcp"],
        "environment": {
          "TELEGRAM_ADS_TOKEN": "your-token",
          "TG_ADS_MODE": "read-only",
          "TG_ADS_CODE_MODE": "read-only"
        },
        "codemode": false
      }
    }
  }
}

OpenCode V2 uses the mcp.servers shape. codemode: false keeps the 24 tools directly callable; use the server's own tg_execute when you want sandboxed scripts.

claude mcp add telegram-ads --scope user \
  --env TELEGRAM_ADS_TOKEN=<your-token> \
  --env TG_ADS_MODE=read-only \
  -- npx -y telegram-ads-mcp

codex mcp add telegram-ads \
  --env TELEGRAM_ADS_TOKEN=<your-token> \
  --env TG_ADS_MODE=read-only \
  -- npx -y telegram-ads-mcp

3. Ask your agent to start

Restart the client and ask:

Use tg_get_account to show my Telegram Ads account and currency.

Then try a read-only report:

Use tg_get_stats for the last 30 days, daily interval, and summarize spend, views, CTR and CPM.

Configuration

All configuration is environment-based. The server never reads .env files implicitly; load them explicitly with node --env-file=.env if you prefer a file.

Variable

Default

Description

TELEGRAM_ADS_TOKEN

required

API token from https://ads.telegram.org/account/api.

TG_ADS_TOKEN

—

Alias for TELEGRAM_ADS_TOKEN.

TG_ADS_MODE

read-only

read-only or write. Write tools are blocked unless this is write.

TG_ADS_CODE_MODE

read-only

off, read-only or write. Controls tg_execute.

TG_ADS_ALLOWED_ACCOUNTS

all

Comma-separated allowlist for explicit account_id values.

TG_ADS_MAX_CPM

no cap

Maximum CPM accepted by the server, in account currency.

TG_ADS_MAX_AD_BUDGET

no cap

Maximum ad budget or budget transfer per call.

TG_ADS_MAX_DAILY_BUDGET

no cap

Maximum daily budget limit per call.

TG_ADS_AUDIT_LOG

disabled

Path to a JSONL audit log. Parent directories are created.

TG_ADS_TIMEOUT_MS

30000

Per-request timeout in milliseconds.

TG_ADS_BASE_URL

official API

Override only for testing. The token is sent to this URL.

Caps apply per call. They are a guardrail, not a full budgeting system: a loop of approved calls can still spend more than a single cap. Use TG_ADS_ALLOWED_ACCOUNTS and the read-only default when you want hard limits on what an agent can touch.

Currency precision

Telegram rejects values with too many decimals. The server validates them before sending:

Currency

CPM and budgets

Amounts (transfers, account budget)

EUR

2 decimals

5 decimals

TON

2 decimals

5 decimals

XTR

0 decimals

3 decimals

tg_get_account returns the account currency. tg_create_ad and tg_ad_budget refuse mismatched precision with a clear error.

Safety model

The server is designed to be useful to an agent without giving it uncontrolled access to money.

  1. Read-only by default. TG_ADS_MODE defaults to read-only. Every write tool fails before it reaches the API.

  2. Per-call confirmation. In write mode, every write also requires confirm: true. The model must decide to pass it, and the call is visible in the transcript.

  3. New ads start paused with zero budget. tg_create_ad defaults is_paused to true and initial_budget to 0. Funding is a separate, explicit step.

  4. Dry runs. tg_create_ad and tg_update_ad accept dry_run: true to show the exact payload and currency without calling the API.

  5. Account allowlist. TG_ADS_ALLOWED_ACCOUNTS rejects explicit account_id values outside the list.

  6. Budget caps. TG_ADS_MAX_CPM, TG_ADS_MAX_AD_BUDGET and TG_ADS_MAX_DAILY_BUDGET reject oversized values before the request is sent.

  7. Idempotency. Every write carries an Idempotency-Key; retries reuse the same key. Tools accept an explicit key when the caller needs to retry safely.

  8. Audit log. Set TG_ADS_AUDIT_LOG to keep a JSONL record of tool calls. Phone numbers, emails and legal names are summarized, and ad text/code is reduced to its length.

  9. No token in logs. The token is never included in tool output, errors or the audit log.

Code Mode adds a second gate: writes inside tg_execute require TG_ADS_MODE=write, TG_ADS_CODE_MODE=write and confirm: true on the tg_execute call.

Tools

Every tool returns JSON text. Errors are returned with isError: true and a stable code such as WRITE_DISABLED, CONFIRMATION_REQUIRED, UNAUTHORIZED or CHANNEL_ID_UNKNOWN.

Account

Tool

Access

Purpose

tg_get_account

read

Current account, currency, budgets. Optionally list related accounts.

tg_get_account_info

read

Billing/profile details (company, email, phone, country, city).

tg_account_budget

write

Increase or decrease a related account's budget.

Advertisements

Tool

Access

Purpose

tg_list_ads

read

Paged ad list with status, budgets and lifetime metrics.

tg_get_ads

read

Up to 100 ads by ID, including decline reasons.

tg_create_ad

write

Create a paused, zero-budget ad. Supports dry_run.

tg_update_ad

write

Edit fields, pause/resume, or submit for review. Supports dry_run.

tg_ad_budget

write

Move funds into or out of an ad.

tg_delete_ad

write

Delete an inactive ad with no remaining budget.

tg_upload_media

write

Upload ad photos, videos or website photos from a local path.

Statistics

Tool

Access

Purpose

tg_get_stats

read

Account or per-ad stats, with totals and CTR/CPM/CPC.

tg_get_report

read

Telegram's monthly account report.

Targeting

Tool

Access

Purpose

tg_list_targeting

read

Languages, topics, countries, locations, channels and bots.

Audiences and pixels

Tool

Access

Purpose

tg_list_audiences

read

List or fetch retargeting audiences.

tg_manage_audience

write

Create, edit or delete a phone-number audience.

tg_get_pixel

read

Pixel ID and installation snippet.

tg_list_pixel_events

read

List or fetch conversion events.

tg_manage_pixel

write

Create the pixel, create/rename/delete events.

Transactions

Tool

Access

Purpose

tg_list_transactions

read

Account-level or ad-level transaction history.

tg_get_transaction

read

Status of a budget transaction.

Advanced

Tool

Access

Purpose

tg_search

read

Search all official methods by name, description or parameter.

tg_get_sdk

read

TypeScript declarations for the Code Mode tg namespace.

tg_execute

sandboxed

Run JavaScript with sequential API calls in QuickJS.

tg_api_call

read/write

Escape hatch for any method without a dedicated tool.

The server also exposes:

  • Resources: telegram-ads://guide, telegram-ads://method-catalog, telegram-ads://sdk.d.ts

  • Prompts: launch-ad, audit-account, weekly-report

Code Mode

Code Mode lets an agent run one short JavaScript program instead of dozens of tool calls: bulk edits, pagination, joins, cross-ad analysis and compact reports.

const ads = await tg.getAdsList({ limit: 100 });
const active = ads.ads.filter((ad) => ad.status === "active");
return active
  .sort((a, b) => (b.spent_budget ?? 0) - (a.spent_budget ?? 0))
  .map((ad) => ({
    id: ad.ad_id,
    title: ad.title,
    spent: ad.spent_budget,
    cpm: ad.cpm,
  }));

Limits and guarantees:

  • QuickJS (WebAssembly) sandbox with no network, filesystem, process or environment access.

  • Only the tg object and console are exposed.

  • Calls run sequentially, so scripts are deterministic and cannot burst the API.

  • At most 25 API calls, 15 seconds, 64 MB of memory and 64 KB of output per run.

  • Read-only unless TG_ADS_MODE=write and TG_ADS_CODE_MODE=write, and tg_execute is called with confirm: true.

See docs/code-mode.md for examples and the full security model.

CLI

telegram-ads-mcp serve              Start the MCP server over stdio (default)
telegram-ads-mcp doctor             Check configuration and verify the token
telegram-ads-mcp init               Write MCP client configuration
telegram-ads-mcp --version          Print the version

init options:

--client <name...>   claude-desktop, cursor, opencode, claude-code, codex, or all
--token <token>      Defaults to TELEGRAM_ADS_TOKEN
--mode <mode>        read-only or write (default: read-only)
--code-mode <mode>   off, read-only or write (default: read-only)
--local <path>       Launch a built local checkout instead of npx
--github             Launch github:furkankoykiran/telegram-ads-mcp instead of the npm package
--print              Print the configuration without writing files

The token is stored in plain text in the generated client config. Keep that file private and revoke the token at https://ads.telegram.org/account/api if it is exposed.

Development

npm install
npm run typecheck
npm run lint
npm test
npm run build

Script

Purpose

npm run dev

Run the CLI from source with tsx.

npm run check

Typecheck, lint and test in one pass.

npm run sync-catalog

Re-parse the official docs and regenerate src/api/catalog.ts.

npm run format

Format the repository with Prettier.

Project layout:

src/
  api/          Catalog, shared types and the HTTP client
  code-mode/    QuickJS sandbox and generated SDK declarations
  tools/        MCP tool registrations
  cli.ts        serve / doctor / init
  server.ts     McpServer assembly
  policy.ts     Write gates, account allowlist and budget caps
  audit.ts      Optional JSONL audit log
tests/
  unit/         Money, client, policy, sandbox, catalog, schemas
  contract/     End-to-end MCP client/server contract tests

The method catalog is generated from https://ads.telegram.org/docs/api. If Telegram ships a new API revision, run npm run sync-catalog, review the diff and update the tools that need new fields. Do not edit src/api/catalog.ts by hand.

Troubleshooting

Symptom

Fix

UNAUTHORIZED / HTTP 401

The token is invalid or revoked. Create a new one at https://ads.telegram.org/account/api.

WRITE_DISABLED

Set TG_ADS_MODE=write in the server environment and restart the client.

CONFIRMATION_REQUIRED

Re-run the write with confirm: true after checking the parameters.

CHANNEL_ID_UNKNOWN / BOT_ID_UNKNOWN

Use @username first so the account resolves it, then numeric IDs will work.

IDEMPOTENT_PARAM_MISMATCH

The key was already used with different parameters. Retry with a new key.

IDEMPOTENT_REQUEST_IN_PROGRESS

An identical request is still running. Wait and retry with the same key.

Precision errors

Check the account currency with tg_get_account; EUR/TON use 2 decimals for CPM, XTR uses 0.

Stats range error

Use an interval of 300 or 86400 seconds and at most 1000 intervals; the server splits larger ranges.

Client does not see the server

Restart the client after editing its config, and check that node --version is 22.18 or newer.

Security

Please read SECURITY.md before using write mode in production. Report vulnerabilities through GitHub's private vulnerability reporting, not in a public issue.

License

MIT © Furkan Koykiran. See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that lets AI agents read and manage Telegram Ads campaigns, including listing accounts and ads, reading stats and budgets, and creating/updating ads, CPM, status, and budget by driving the real ads.telegram.org web UI through Playwright with a reused cookie-based login session.
      11
      1
      MIT
    • F
      license
      A
      quality
      B
      maintenance
      Enables AI agents to create, target, pause, and read stats for Telegram Ads campaigns through ads.telegram.org using a logged-in session, with tools for managing ads, creatives, targeting, and account settings.
      26
      4
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to operate a Telegram account through the same commands as the terminal client: messaging, chat management, voice transcription, calls, stickers, and privacy settings.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to manage Telegram chats, messages, contacts, users, groups, and channels via 50+ MCP tools, with a reactive inbox and per-topic proxy isolation for multi-agent setups.
      MIT