Skip to content
Back to search

telegram-ads-mcp

Open-source MCP server for the official Telegram Ads API. Manage accounts, ads, stats, audiences, pixels, and targeting from Claude, Cursor, Codex, and other AI agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/furkankoykiran--telegram-ads-mcp/badge.svg)](/listings/furkankoykiran--telegram-ads-mcp)

HTML

<a href="/listings/furkankoykiran--telegram-ads-mcp"><img src="/api/listings/furkankoykiran--telegram-ads-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- Node.js **22.18 or newer** (24 LTS recommended) - A Telegram Ads account with access to the API - An API token from <https://ads.telegram.org/account/api>

1. Connect the server

The package is published on npm as `telegram-ads-mcp` and listed in the official [MCP Registry](https://registry.modelcontextprotocol.io/?q=io.github.furkankoykiran%2Ftelegram-ads) as `io.github.furkankoykiran/telegram-ads`. Run:

npx -y telegram-ads-mcp doctor

To run the latest commit from GitHub instead of the npm release, use:

npx -y github:furkankoykiran/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>

To launch the GitHub package instead of the npm release, add `--github`:

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.

<details> <summary>Claude Desktop / Cursor JSON</summary>

{
  "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"
      }
    }
  }
}

</details>

<details> <summary>OpenCode JSON</summary>

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

</details>

<details> <summary>Claude Code and Codex</summary>

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

</details>

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 426 lines
  1. <p align="center">
  2. <img src="assets/logo.svg" width="112" height="112" alt="Telegram Ads MCP logo">
  3. </p>
  4. <h1 align="center">Telegram Ads MCP</h1>
  5. <p align="center">
  6. <a href="https://github.com/furkankoykiran/telegram-ads-mcp/actions/workflows/ci.yml"><img src="https://github.com/furkankoykiran/telegram-ads-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  7. <a href="https://registry.modelcontextprotocol.io/?q=io.github.furkankoykiran%2Ftelegram-ads"><img src="https://img.shields.io/badge/MCP%20Registry-listed-6f42c1" alt="MCP Registry"></a>
  8. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
  9. <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D22.18-339933?logo=node.js&logoColor=white" alt="Node.js 22.18 or newer"></a>
  10. <a href="https://www.typescriptlang.org"><img src="https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white" alt="TypeScript strict"></a>
  11. </p>
  12. An open-source [Model Context Protocol](https://modelcontextprotocol.io) server for the **official
  13. Telegram Ads API**. Manage accounts, advertisements, budgets, statistics, audiences, pixels and
  14. targeting from Claude, Cursor, Codex, OpenCode or any MCP-compatible client.
  15. - **Official API only.** No cookies, browser automation or private endpoints.
  16. - **Local-first.** Runs over stdio on your machine. Your token never leaves it except to call
  17. `promoteapi.telegram.org`.
  18. - **Safe by default.** Read-only mode, explicit write confirmation, budget caps, idempotency keys and
  19. an optional JSONL audit log.
  20. - **Built for agents.** 24 focused tools, a searchable catalog of all 45 official methods, guided
  21. prompts, and an optional sandboxed Code Mode for multi-step work.
  22. > This project is unofficial and is not affiliated with, endorsed by or sponsored by Telegram. The
  23. > Telegram name and logo are trademarks of their respective owners.
  24. ## Contents
  25. - [Quick start](#quick-start)
  26. - [Configuration](#configuration)
  27. - [Safety model](#safety-model)
  28. - [Tools](#tools)
  29. - [Code Mode](#code-mode)
  30. - [CLI](#cli)
  31. - [Development](#development)
  32. - [Troubleshooting](#troubleshooting)
  33. - [Security](#security)
  34. - [License](#license)
  35. ## Quick start
  36. ### Prerequisites
  37. - Node.js **22.18 or newer** (24 LTS recommended)
  38. - A Telegram Ads account with access to the API
  39. - An API token from <https://ads.telegram.org/account/api>
  40. ### 1. Connect the server
  41. The package is published on npm as `telegram-ads-mcp` and listed in the official
  42. [MCP Registry](https://registry.modelcontextprotocol.io/?q=io.github.furkankoykiran%2Ftelegram-ads)
  43. as `io.github.furkankoykiran/telegram-ads`. Run:
  44. ```bash
  45. npx -y telegram-ads-mcp doctor
  46. ```
  47. To run the latest commit from GitHub instead of the npm release, use:
  48. ```bash
  49. npx -y github:furkankoykiran/telegram-ads-mcp doctor
  50. ```
  51. Or build a local checkout:
  52. ```bash
  53. git clone https://github.com/furkankoykiran/telegram-ads-mcp.git
  54. cd telegram-ads-mcp
  55. npm install
  56. node dist/cli.js doctor
  57. ```
  58. `doctor` checks the token against the API and prints the account currency and budget. It is the
  59. fastest way to confirm everything works.
  60. ### 2. Write your client configuration
  61. `init` writes the correct file for each client and keeps a `.bak` copy of an existing config:
  62. ```bash
  63. npx -y telegram-ads-mcp init --client claude-desktop --token <your-token>
  64. npx -y telegram-ads-mcp init --client cursor --token <your-token>
  65. npx -y telegram-ads-mcp init --client opencode --token <your-token>
  66. npx -y telegram-ads-mcp init --client all --token <your-token>
  67. ```
  68. To launch the GitHub package instead of the npm release, add `--github`:
  69. ```bash
  70. npx -y github:furkankoykiran/telegram-ads-mcp init --client all --github --token <your-token>
  71. ```
  72. For a local checkout, add `--local .` so the generated config launches `node dist/cli.js` instead of
  73. `npx`:
  74. ```bash
  75. node dist/cli.js init --client claude-desktop --local . --token <your-token>
  76. ```
  77. Prefer to edit files by hand? `--print` prints the merged configuration without writing anything.
  78. Claude Code and Codex are CLI-based; `init` prints the exact `claude mcp add` / `codex mcp add`
  79. command instead of editing their config.
  80. <details>
  81. <summary>Claude Desktop / Cursor JSON</summary>
  82. ```json
  83. {
  84. "mcpServers": {
  85. "telegram-ads": {
  86. "command": "npx",
  87. "args": ["-y", "telegram-ads-mcp"],
  88. "env": {
  89. "TELEGRAM_ADS_TOKEN": "your-token",
  90. "TG_ADS_MODE": "read-only",
  91. "TG_ADS_CODE_MODE": "read-only"
  92. }
  93. }
  94. }
  95. }
  96. ```
  97. </details>
  98. <details>
  99. <summary>OpenCode JSON</summary>
  100. ```json
  101. {
  102. "mcp": {
  103. "servers": {
  104. "telegram-ads": {
  105. "type": "local",
  106. "command": ["npx", "-y", "telegram-ads-mcp"],
  107. "environment": {
  108. "TELEGRAM_ADS_TOKEN": "your-token",
  109. "TG_ADS_MODE": "read-only",
  110. "TG_ADS_CODE_MODE": "read-only"
  111. },
  112. "codemode": false
  113. }
  114. }
  115. }
  116. }
  117. ```
  118. OpenCode V2 uses the `mcp.servers` shape. `codemode: false` keeps the 24 tools directly callable;
  119. use the server's own `tg_execute` when you want sandboxed scripts.
  120. </details>
  121. <details>
  122. <summary>Claude Code and Codex</summary>
  123. ```bash
  124. claude mcp add telegram-ads --scope user \
  125. --env TELEGRAM_ADS_TOKEN=<your-token> \
  126. --env TG_ADS_MODE=read-only \
  127. -- npx -y telegram-ads-mcp
  128. codex mcp add telegram-ads \
  129. --env TELEGRAM_ADS_TOKEN=<your-token> \
  130. --env TG_ADS_MODE=read-only \
  131. -- npx -y telegram-ads-mcp
  132. ```
  133. </details>
  134. ### 3. Ask your agent to start
  135. Restart the client and ask:
  136. > Use `tg_get_account` to show my Telegram Ads account and currency.
  137. Then try a read-only report:
  138. > Use `tg_get_stats` for the last 30 days, daily interval, and summarize spend, views, CTR and CPM.
  139. ## Configuration
  140. All configuration is environment-based. The server never reads `.env` files implicitly; load them
  141. explicitly with `node --env-file=.env` if you prefer a file.
  142. | Variable | Default | Description |
  143. | ------------------------- | ------------ | ----------------------------------------------------------------------- |
  144. | `TELEGRAM_ADS_TOKEN` | required | API token from <https://ads.telegram.org/account/api>. |
  145. | `TG_ADS_TOKEN` | — | Alias for `TELEGRAM_ADS_TOKEN`. |
  146. | `TG_ADS_MODE` | `read-only` | `read-only` or `write`. Write tools are blocked unless this is `write`. |
  147. | `TG_ADS_CODE_MODE` | `read-only` | `off`, `read-only` or `write`. Controls `tg_execute`. |
  148. | `TG_ADS_ALLOWED_ACCOUNTS` | all | Comma-separated allowlist for explicit `account_id` values. |
  149. | `TG_ADS_MAX_CPM` | no cap | Maximum CPM accepted by the server, in account currency. |
  150. | `TG_ADS_MAX_AD_BUDGET` | no cap | Maximum ad budget or budget transfer per call. |
  151. | `TG_ADS_MAX_DAILY_BUDGET` | no cap | Maximum daily budget limit per call. |
  152. | `TG_ADS_AUDIT_LOG` | disabled | Path to a JSONL audit log. Parent directories are created. |
  153. | `TG_ADS_TIMEOUT_MS` | `30000` | Per-request timeout in milliseconds. |
  154. | `TG_ADS_BASE_URL` | official API | Override only for testing. The token is sent to this URL. |
  155. Caps apply **per call**. They are a guardrail, not a full budgeting system: a loop of approved
  156. calls can still spend more than a single cap. Use `TG_ADS_ALLOWED_ACCOUNTS` and the read-only
  157. default when you want hard limits on what an agent can touch.
  158. ### Currency precision
  159. Telegram rejects values with too many decimals. The server validates them before sending:
  160. | Currency | CPM and budgets | Amounts (transfers, account budget) |
  161. | -------- | --------------- | ----------------------------------- |
  162. | EUR | 2 decimals | 5 decimals |
  163. | TON | 2 decimals | 5 decimals |
  164. | XTR | 0 decimals | 3 decimals |
  165. `tg_get_account` returns the account currency. `tg_create_ad` and `tg_ad_budget` refuse mismatched
  166. precision with a clear error.
  167. ## Safety model
  168. The server is designed to be useful to an agent without giving it uncontrolled access to money.
  169. 1. **Read-only by default.** `TG_ADS_MODE` defaults to `read-only`. Every write tool fails before it
  170. reaches the API.
  171. 2. **Per-call confirmation.** In write mode, every write also requires `confirm: true`. The model
  172. must decide to pass it, and the call is visible in the transcript.
  173. 3. **New ads start paused with zero budget.** `tg_create_ad` defaults `is_paused` to `true` and
  174. `initial_budget` to `0`. Funding is a separate, explicit step.
  175. 4. **Dry runs.** `tg_create_ad` and `tg_update_ad` accept `dry_run: true` to show the exact payload
  176. and currency without calling the API.
  177. 5. **Account allowlist.** `TG_ADS_ALLOWED_ACCOUNTS` rejects explicit `account_id` values outside the
  178. list.
  179. 6. **Budget caps.** `TG_ADS_MAX_CPM`, `TG_ADS_MAX_AD_BUDGET` and `TG_ADS_MAX_DAILY_BUDGET` reject
  180. oversized values before the request is sent.
  181. 7. **Idempotency.** Every write carries an `Idempotency-Key`; retries reuse the same key. Tools
  182. accept an explicit key when the caller needs to retry safely.
  183. 8. **Audit log.** Set `TG_ADS_AUDIT_LOG` to keep a JSONL record of tool calls. Phone numbers, emails
  184. and legal names are summarized, and ad text/code is reduced to its length.
  185. 9. **No token in logs.** The token is never included in tool output, errors or the audit log.
  186. Code Mode adds a second gate: writes inside `tg_execute` require `TG_ADS_MODE=write`,
  187. `TG_ADS_CODE_MODE=write` **and** `confirm: true` on the `tg_execute` call.
  188. ## Tools
  189. Every tool returns JSON text. Errors are returned with `isError: true` and a stable code such as
  190. `WRITE_DISABLED`, `CONFIRMATION_REQUIRED`, `UNAUTHORIZED` or `CHANNEL_ID_UNKNOWN`.
  191. ### Account
  192. | Tool | Access | Purpose |
  193. | --------------------- | ------ | --------------------------------------------------------------------- |
  194. | `tg_get_account` | read | Current account, currency, budgets. Optionally list related accounts. |
  195. | `tg_get_account_info` | read | Billing/profile details (company, email, phone, country, city). |
  196. | `tg_account_budget` | write | Increase or decrease a related account's budget. |
  197. ### Advertisements
  198. | Tool | Access | Purpose |
  199. | ----------------- | ------ | -------------------------------------------------------------------- |
  200. | `tg_list_ads` | read | Paged ad list with status, budgets and lifetime metrics. |
  201. | `tg_get_ads` | read | Up to 100 ads by ID, including decline reasons. |
  202. | `tg_create_ad` | write | Create a paused, zero-budget ad. Supports `dry_run`. |
  203. | `tg_update_ad` | write | Edit fields, pause/resume, or submit for review. Supports `dry_run`. |
  204. | `tg_ad_budget` | write | Move funds into or out of an ad. |
  205. | `tg_delete_ad` | write | Delete an inactive ad with no remaining budget. |
  206. | `tg_upload_media` | write | Upload ad photos, videos or website photos from a local path. |
  207. ### Statistics
  208. | Tool | Access | Purpose |
  209. | --------------- | ------ | ----------------------------------------------------- |
  210. | `tg_get_stats` | read | Account or per-ad stats, with totals and CTR/CPM/CPC. |
  211. | `tg_get_report` | read | Telegram's monthly account report. |
  212. ### Targeting
  213. | Tool | Access | Purpose |
  214. | ------------------- | ------ | ----------------------------------------------------------- |
  215. | `tg_list_targeting` | read | Languages, topics, countries, locations, channels and bots. |
  216. ### Audiences and pixels
  217. | Tool | Access | Purpose |
  218. | ---------------------- | ------ | ----------------------------------------------- |
  219. | `tg_list_audiences` | read | List or fetch retargeting audiences. |
  220. | `tg_manage_audience` | write | Create, edit or delete a phone-number audience. |
  221. | `tg_get_pixel` | read | Pixel ID and installation snippet. |
  222. | `tg_list_pixel_events` | read | List or fetch conversion events. |
  223. | `tg_manage_pixel` | write | Create the pixel, create/rename/delete events. |
  224. ### Transactions
  225. | Tool | Access | Purpose |
  226. | ---------------------- | ------ | ---------------------------------------------- |
  227. | `tg_list_transactions` | read | Account-level or ad-level transaction history. |
  228. | `tg_get_transaction` | read | Status of a budget transaction. |
  229. ### Advanced
  230. | Tool | Access | Purpose |
  231. | ------------- | ---------- | -------------------------------------------------------------- |
  232. | `tg_search` | read | Search all official methods by name, description or parameter. |
  233. | `tg_get_sdk` | read | TypeScript declarations for the Code Mode `tg` namespace. |
  234. | `tg_execute` | sandboxed | Run JavaScript with sequential API calls in QuickJS. |
  235. | `tg_api_call` | read/write | Escape hatch for any method without a dedicated tool. |
  236. The server also exposes:
  237. - **Resources:** `telegram-ads://guide`, `telegram-ads://method-catalog`, `telegram-ads://sdk.d.ts`
  238. - **Prompts:** `launch-ad`, `audit-account`, `weekly-report`
  239. ## Code Mode
  240. Code Mode lets an agent run one short JavaScript program instead of dozens of tool calls: bulk
  241. edits, pagination, joins, cross-ad analysis and compact reports.
  242. ```js
  243. const ads = await tg.getAdsList({ limit: 100 });
  244. const active = ads.ads.filter((ad) => ad.status === "active");
  245. return active
  246. .sort((a, b) => (b.spent_budget ?? 0) - (a.spent_budget ?? 0))
  247. .map((ad) => ({
  248. id: ad.ad_id,
  249. title: ad.title,
  250. spent: ad.spent_budget,
  251. cpm: ad.cpm,
  252. }));
  253. ```
  254. Limits and guarantees:
  255. - QuickJS (WebAssembly) sandbox with **no network, filesystem, process or environment access**.
  256. - Only the `tg` object and `console` are exposed.
  257. - Calls run **sequentially**, so scripts are deterministic and cannot burst the API.
  258. - At most **25 API calls**, **15 seconds**, **64 MB** of memory and **64 KB** of output per run.
  259. - Read-only unless `TG_ADS_MODE=write` **and** `TG_ADS_CODE_MODE=write`, and `tg_execute` is called
  260. with `confirm: true`.
  261. See [docs/code-mode.md](docs/code-mode.md) for examples and the full security model.
  262. ## CLI
  263. ```text
  264. telegram-ads-mcp serve Start the MCP server over stdio (default)
  265. telegram-ads-mcp doctor Check configuration and verify the token
  266. telegram-ads-mcp init Write MCP client configuration
  267. telegram-ads-mcp --version Print the version
  268. ```
  269. `init` options:
  270. ```text
  271. --client <name...> claude-desktop, cursor, opencode, claude-code, codex, or all
  272. --token <token> Defaults to TELEGRAM_ADS_TOKEN
  273. --mode <mode> read-only or write (default: read-only)
  274. --code-mode <mode> off, read-only or write (default: read-only)
  275. --local <path> Launch a built local checkout instead of npx
  276. --github Launch github:furkankoykiran/telegram-ads-mcp instead of the npm package
  277. --print Print the configuration without writing files
  278. ```
  279. The token is stored in plain text in the generated client config. Keep that file private and revoke
  280. the token at <https://ads.telegram.org/account/api> if it is exposed.
  281. ## Development
  282. ```bash
  283. npm install
  284. npm run typecheck
  285. npm run lint
  286. npm test
  287. npm run build
  288. ```
  289. | Script | Purpose |
  290. | ---------------------- | --------------------------------------------------------------- |
  291. | `npm run dev` | Run the CLI from source with `tsx`. |
  292. | `npm run check` | Typecheck, lint and test in one pass. |
  293. | `npm run sync-catalog` | Re-parse the official docs and regenerate `src/api/catalog.ts`. |
  294. | `npm run format` | Format the repository with Prettier. |
  295. Project layout:
  296. ```text
  297. src/
  298. api/ Catalog, shared types and the HTTP client
  299. code-mode/ QuickJS sandbox and generated SDK declarations
  300. tools/ MCP tool registrations
  301. cli.ts serve / doctor / init
  302. server.ts McpServer assembly
  303. policy.ts Write gates, account allowlist and budget caps
  304. audit.ts Optional JSONL audit log
  305. tests/
  306. unit/ Money, client, policy, sandbox, catalog, schemas
  307. contract/ End-to-end MCP client/server contract tests
  308. ```
  309. The method catalog is generated from <https://ads.telegram.org/docs/api>. If Telegram ships a new
  310. API revision, run `npm run sync-catalog`, review the diff and update the tools that need new fields.
  311. Do not edit `src/api/catalog.ts` by hand.
  312. Release steps and the one-time trusted publishing setup are documented in
  313. [docs/releasing.md](docs/releasing.md).
  314. ## Troubleshooting
  315. | Symptom | Fix |
  316. | --------------------------------------- | ---------------------------------------------------------------------------------------------------- |
  317. | `UNAUTHORIZED` / HTTP 401 | The token is invalid or revoked. Create a new one at <https://ads.telegram.org/account/api>. |
  318. | `WRITE_DISABLED` | Set `TG_ADS_MODE=write` in the server environment and restart the client. |
  319. | `CONFIRMATION_REQUIRED` | Re-run the write with `confirm: true` after checking the parameters. |
  320. | `CHANNEL_ID_UNKNOWN` / `BOT_ID_UNKNOWN` | Use `@username` first so the account resolves it, then numeric IDs will work. |
  321. | `IDEMPOTENT_PARAM_MISMATCH` | The key was already used with different parameters. Retry with a new key. |
  322. | `IDEMPOTENT_REQUEST_IN_PROGRESS` | An identical request is still running. Wait and retry with the same key. |
  323. | Precision errors | Check the account currency with `tg_get_account`; EUR/TON use 2 decimals for CPM, XTR uses 0. |
  324. | Stats range error | Use an interval of 300 or 86400 seconds and at most 1000 intervals; the server splits larger ranges. |
  325. | Client does not see the server | Restart the client after editing its config, and check that `node --version` is 22.18 or newer. |
  326. ## Security
  327. Please read [SECURITY.md](SECURITY.md) before using write mode in production. Report vulnerabilities
  328. through GitHub's private vulnerability reporting, not in a public issue.
  329. ## License
  330. MIT © Furkan Koykiran. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.