telegram-ads-mcp 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +420 -2
- package/assets/logo.svg +18 -0
- package/dist/cli.d.ts +1 -0
- package/dist/cli.js +3948 -0
- package/dist/cli.js.map +1 -0
- package/dist/index.d.ts +376 -0
- package/dist/index.js +3719 -0
- package/dist/index.js.map +1 -0
- package/package.json +84 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Furkan Koykiran
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,421 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="assets/logo.svg" width="112" height="112" alt="Telegram Ads MCP logo">
|
|
3
|
+
</p>
|
|
2
4
|
|
|
3
|
-
|
|
5
|
+
<h1 align="center">Telegram Ads MCP</h1>
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
<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>
|
|
9
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
|
|
10
|
+
<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>
|
|
11
|
+
<a href="https://www.typescriptlang.org"><img src="https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white" alt="TypeScript strict"></a>
|
|
12
|
+
</p>
|
|
13
|
+
|
|
14
|
+
An open-source [Model Context Protocol](https://modelcontextprotocol.io) server for the **official
|
|
15
|
+
Telegram Ads API**. Manage accounts, advertisements, budgets, statistics, audiences, pixels and
|
|
16
|
+
targeting from Claude, Cursor, Codex, OpenCode or any MCP-compatible client.
|
|
17
|
+
|
|
18
|
+
- **Official API only.** No cookies, browser automation or private endpoints.
|
|
19
|
+
- **Local-first.** Runs over stdio on your machine. Your token never leaves it except to call
|
|
20
|
+
`promoteapi.telegram.org`.
|
|
21
|
+
- **Safe by default.** Read-only mode, explicit write confirmation, budget caps, idempotency keys and
|
|
22
|
+
an optional JSONL audit log.
|
|
23
|
+
- **Built for agents.** 24 focused tools, a searchable catalog of all 45 official methods, guided
|
|
24
|
+
prompts, and an optional sandboxed Code Mode for multi-step work.
|
|
25
|
+
|
|
26
|
+
> This project is unofficial and is not affiliated with, endorsed by or sponsored by Telegram. The
|
|
27
|
+
> Telegram name and logo are trademarks of their respective owners.
|
|
28
|
+
|
|
29
|
+
## Contents
|
|
30
|
+
|
|
31
|
+
- [Quick start](#quick-start)
|
|
32
|
+
- [Configuration](#configuration)
|
|
33
|
+
- [Safety model](#safety-model)
|
|
34
|
+
- [Tools](#tools)
|
|
35
|
+
- [Code Mode](#code-mode)
|
|
36
|
+
- [CLI](#cli)
|
|
37
|
+
- [Development](#development)
|
|
38
|
+
- [Troubleshooting](#troubleshooting)
|
|
39
|
+
- [Security](#security)
|
|
40
|
+
- [License](#license)
|
|
41
|
+
|
|
42
|
+
## Quick start
|
|
43
|
+
|
|
44
|
+
### Prerequisites
|
|
45
|
+
|
|
46
|
+
- Node.js **22.18 or newer** (24 LTS recommended)
|
|
47
|
+
- A Telegram Ads account with access to the API
|
|
48
|
+
- An API token from <https://ads.telegram.org/account/api>
|
|
49
|
+
|
|
50
|
+
### 1. Connect the server
|
|
51
|
+
|
|
52
|
+
The package name is `telegram-ads-mcp`. Until the first npm release is available, install straight
|
|
53
|
+
from GitHub; npm builds the package automatically:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
npx -y github:furkankoykiran/telegram-ads-mcp doctor
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
After the npm release, the shorter form works too:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
npx -y telegram-ads-mcp doctor
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Or build a local checkout:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
git clone https://github.com/furkankoykiran/telegram-ads-mcp.git
|
|
69
|
+
cd telegram-ads-mcp
|
|
70
|
+
npm install
|
|
71
|
+
node dist/cli.js doctor
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
`doctor` checks the token against the API and prints the account currency and budget. It is the
|
|
75
|
+
fastest way to confirm everything works.
|
|
76
|
+
|
|
77
|
+
### 2. Write your client configuration
|
|
78
|
+
|
|
79
|
+
`init` writes the correct file for each client and keeps a `.bak` copy of an existing config:
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
npx -y telegram-ads-mcp init --client claude-desktop --token <your-token>
|
|
83
|
+
npx -y telegram-ads-mcp init --client cursor --token <your-token>
|
|
84
|
+
npx -y telegram-ads-mcp init --client opencode --token <your-token>
|
|
85
|
+
npx -y telegram-ads-mcp init --client all --token <your-token>
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Before the npm release, add `--github` so the generated config launches the GitHub package instead:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
npx -y github:furkankoykiran/telegram-ads-mcp init --client all --github --token <your-token>
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
For a local checkout, add `--local .` so the generated config launches `node dist/cli.js` instead of
|
|
95
|
+
`npx`:
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
node dist/cli.js init --client claude-desktop --local . --token <your-token>
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Prefer to edit files by hand? `--print` prints the merged configuration without writing anything.
|
|
102
|
+
Claude Code and Codex are CLI-based; `init` prints the exact `claude mcp add` / `codex mcp add`
|
|
103
|
+
command instead of editing their config.
|
|
104
|
+
|
|
105
|
+
<details>
|
|
106
|
+
<summary>Claude Desktop / Cursor JSON</summary>
|
|
107
|
+
|
|
108
|
+
```json
|
|
109
|
+
{
|
|
110
|
+
"mcpServers": {
|
|
111
|
+
"telegram-ads": {
|
|
112
|
+
"command": "npx",
|
|
113
|
+
"args": ["-y", "telegram-ads-mcp"],
|
|
114
|
+
"env": {
|
|
115
|
+
"TELEGRAM_ADS_TOKEN": "your-token",
|
|
116
|
+
"TG_ADS_MODE": "read-only",
|
|
117
|
+
"TG_ADS_CODE_MODE": "read-only"
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
</details>
|
|
125
|
+
|
|
126
|
+
<details>
|
|
127
|
+
<summary>OpenCode JSON</summary>
|
|
128
|
+
|
|
129
|
+
```json
|
|
130
|
+
{
|
|
131
|
+
"mcp": {
|
|
132
|
+
"servers": {
|
|
133
|
+
"telegram-ads": {
|
|
134
|
+
"type": "local",
|
|
135
|
+
"command": ["npx", "-y", "telegram-ads-mcp"],
|
|
136
|
+
"environment": {
|
|
137
|
+
"TELEGRAM_ADS_TOKEN": "your-token",
|
|
138
|
+
"TG_ADS_MODE": "read-only",
|
|
139
|
+
"TG_ADS_CODE_MODE": "read-only"
|
|
140
|
+
},
|
|
141
|
+
"codemode": false
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
OpenCode V2 uses the `mcp.servers` shape. `codemode: false` keeps the 24 tools directly callable;
|
|
149
|
+
use the server's own `tg_execute` when you want sandboxed scripts.
|
|
150
|
+
|
|
151
|
+
</details>
|
|
152
|
+
|
|
153
|
+
<details>
|
|
154
|
+
<summary>Claude Code and Codex</summary>
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
claude mcp add telegram-ads --scope user \
|
|
158
|
+
--env TELEGRAM_ADS_TOKEN=<your-token> \
|
|
159
|
+
--env TG_ADS_MODE=read-only \
|
|
160
|
+
-- npx -y telegram-ads-mcp
|
|
161
|
+
|
|
162
|
+
codex mcp add telegram-ads \
|
|
163
|
+
--env TELEGRAM_ADS_TOKEN=<your-token> \
|
|
164
|
+
--env TG_ADS_MODE=read-only \
|
|
165
|
+
-- npx -y telegram-ads-mcp
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
</details>
|
|
169
|
+
|
|
170
|
+
### 3. Ask your agent to start
|
|
171
|
+
|
|
172
|
+
Restart the client and ask:
|
|
173
|
+
|
|
174
|
+
> Use `tg_get_account` to show my Telegram Ads account and currency.
|
|
175
|
+
|
|
176
|
+
Then try a read-only report:
|
|
177
|
+
|
|
178
|
+
> Use `tg_get_stats` for the last 30 days, daily interval, and summarize spend, views, CTR and CPM.
|
|
179
|
+
|
|
180
|
+
## Configuration
|
|
181
|
+
|
|
182
|
+
All configuration is environment-based. The server never reads `.env` files implicitly; load them
|
|
183
|
+
explicitly with `node --env-file=.env` if you prefer a file.
|
|
184
|
+
|
|
185
|
+
| Variable | Default | Description |
|
|
186
|
+
| ------------------------- | ------------ | ----------------------------------------------------------------------- |
|
|
187
|
+
| `TELEGRAM_ADS_TOKEN` | required | API token from <https://ads.telegram.org/account/api>. |
|
|
188
|
+
| `TG_ADS_TOKEN` | — | Alias for `TELEGRAM_ADS_TOKEN`. |
|
|
189
|
+
| `TG_ADS_MODE` | `read-only` | `read-only` or `write`. Write tools are blocked unless this is `write`. |
|
|
190
|
+
| `TG_ADS_CODE_MODE` | `read-only` | `off`, `read-only` or `write`. Controls `tg_execute`. |
|
|
191
|
+
| `TG_ADS_ALLOWED_ACCOUNTS` | all | Comma-separated allowlist for explicit `account_id` values. |
|
|
192
|
+
| `TG_ADS_MAX_CPM` | no cap | Maximum CPM accepted by the server, in account currency. |
|
|
193
|
+
| `TG_ADS_MAX_AD_BUDGET` | no cap | Maximum ad budget or budget transfer per call. |
|
|
194
|
+
| `TG_ADS_MAX_DAILY_BUDGET` | no cap | Maximum daily budget limit per call. |
|
|
195
|
+
| `TG_ADS_AUDIT_LOG` | disabled | Path to a JSONL audit log. Parent directories are created. |
|
|
196
|
+
| `TG_ADS_TIMEOUT_MS` | `30000` | Per-request timeout in milliseconds. |
|
|
197
|
+
| `TG_ADS_BASE_URL` | official API | Override only for testing. The token is sent to this URL. |
|
|
198
|
+
|
|
199
|
+
Caps apply **per call**. They are a guardrail, not a full budgeting system: a loop of approved
|
|
200
|
+
calls can still spend more than a single cap. Use `TG_ADS_ALLOWED_ACCOUNTS` and the read-only
|
|
201
|
+
default when you want hard limits on what an agent can touch.
|
|
202
|
+
|
|
203
|
+
### Currency precision
|
|
204
|
+
|
|
205
|
+
Telegram rejects values with too many decimals. The server validates them before sending:
|
|
206
|
+
|
|
207
|
+
| Currency | CPM and budgets | Amounts (transfers, account budget) |
|
|
208
|
+
| -------- | --------------- | ----------------------------------- |
|
|
209
|
+
| EUR | 2 decimals | 5 decimals |
|
|
210
|
+
| TON | 2 decimals | 5 decimals |
|
|
211
|
+
| XTR | 0 decimals | 3 decimals |
|
|
212
|
+
|
|
213
|
+
`tg_get_account` returns the account currency. `tg_create_ad` and `tg_ad_budget` refuse mismatched
|
|
214
|
+
precision with a clear error.
|
|
215
|
+
|
|
216
|
+
## Safety model
|
|
217
|
+
|
|
218
|
+
The server is designed to be useful to an agent without giving it uncontrolled access to money.
|
|
219
|
+
|
|
220
|
+
1. **Read-only by default.** `TG_ADS_MODE` defaults to `read-only`. Every write tool fails before it
|
|
221
|
+
reaches the API.
|
|
222
|
+
2. **Per-call confirmation.** In write mode, every write also requires `confirm: true`. The model
|
|
223
|
+
must decide to pass it, and the call is visible in the transcript.
|
|
224
|
+
3. **New ads start paused with zero budget.** `tg_create_ad` defaults `is_paused` to `true` and
|
|
225
|
+
`initial_budget` to `0`. Funding is a separate, explicit step.
|
|
226
|
+
4. **Dry runs.** `tg_create_ad` and `tg_update_ad` accept `dry_run: true` to show the exact payload
|
|
227
|
+
and currency without calling the API.
|
|
228
|
+
5. **Account allowlist.** `TG_ADS_ALLOWED_ACCOUNTS` rejects explicit `account_id` values outside the
|
|
229
|
+
list.
|
|
230
|
+
6. **Budget caps.** `TG_ADS_MAX_CPM`, `TG_ADS_MAX_AD_BUDGET` and `TG_ADS_MAX_DAILY_BUDGET` reject
|
|
231
|
+
oversized values before the request is sent.
|
|
232
|
+
7. **Idempotency.** Every write carries an `Idempotency-Key`; retries reuse the same key. Tools
|
|
233
|
+
accept an explicit key when the caller needs to retry safely.
|
|
234
|
+
8. **Audit log.** Set `TG_ADS_AUDIT_LOG` to keep a JSONL record of tool calls. Phone numbers, emails
|
|
235
|
+
and legal names are summarized, and ad text/code is reduced to its length.
|
|
236
|
+
9. **No token in logs.** The token is never included in tool output, errors or the audit log.
|
|
237
|
+
|
|
238
|
+
Code Mode adds a second gate: writes inside `tg_execute` require `TG_ADS_MODE=write`,
|
|
239
|
+
`TG_ADS_CODE_MODE=write` **and** `confirm: true` on the `tg_execute` call.
|
|
240
|
+
|
|
241
|
+
## Tools
|
|
242
|
+
|
|
243
|
+
Every tool returns JSON text. Errors are returned with `isError: true` and a stable code such as
|
|
244
|
+
`WRITE_DISABLED`, `CONFIRMATION_REQUIRED`, `UNAUTHORIZED` or `CHANNEL_ID_UNKNOWN`.
|
|
245
|
+
|
|
246
|
+
### Account
|
|
247
|
+
|
|
248
|
+
| Tool | Access | Purpose |
|
|
249
|
+
| --------------------- | ------ | --------------------------------------------------------------------- |
|
|
250
|
+
| `tg_get_account` | read | Current account, currency, budgets. Optionally list related accounts. |
|
|
251
|
+
| `tg_get_account_info` | read | Billing/profile details (company, email, phone, country, city). |
|
|
252
|
+
| `tg_account_budget` | write | Increase or decrease a related account's budget. |
|
|
253
|
+
|
|
254
|
+
### Advertisements
|
|
255
|
+
|
|
256
|
+
| Tool | Access | Purpose |
|
|
257
|
+
| ----------------- | ------ | -------------------------------------------------------------------- |
|
|
258
|
+
| `tg_list_ads` | read | Paged ad list with status, budgets and lifetime metrics. |
|
|
259
|
+
| `tg_get_ads` | read | Up to 100 ads by ID, including decline reasons. |
|
|
260
|
+
| `tg_create_ad` | write | Create a paused, zero-budget ad. Supports `dry_run`. |
|
|
261
|
+
| `tg_update_ad` | write | Edit fields, pause/resume, or submit for review. Supports `dry_run`. |
|
|
262
|
+
| `tg_ad_budget` | write | Move funds into or out of an ad. |
|
|
263
|
+
| `tg_delete_ad` | write | Delete an inactive ad with no remaining budget. |
|
|
264
|
+
| `tg_upload_media` | write | Upload ad photos, videos or website photos from a local path. |
|
|
265
|
+
|
|
266
|
+
### Statistics
|
|
267
|
+
|
|
268
|
+
| Tool | Access | Purpose |
|
|
269
|
+
| --------------- | ------ | ----------------------------------------------------- |
|
|
270
|
+
| `tg_get_stats` | read | Account or per-ad stats, with totals and CTR/CPM/CPC. |
|
|
271
|
+
| `tg_get_report` | read | Telegram's monthly account report. |
|
|
272
|
+
|
|
273
|
+
### Targeting
|
|
274
|
+
|
|
275
|
+
| Tool | Access | Purpose |
|
|
276
|
+
| ------------------- | ------ | ----------------------------------------------------------- |
|
|
277
|
+
| `tg_list_targeting` | read | Languages, topics, countries, locations, channels and bots. |
|
|
278
|
+
|
|
279
|
+
### Audiences and pixels
|
|
280
|
+
|
|
281
|
+
| Tool | Access | Purpose |
|
|
282
|
+
| ---------------------- | ------ | ----------------------------------------------- |
|
|
283
|
+
| `tg_list_audiences` | read | List or fetch retargeting audiences. |
|
|
284
|
+
| `tg_manage_audience` | write | Create, edit or delete a phone-number audience. |
|
|
285
|
+
| `tg_get_pixel` | read | Pixel ID and installation snippet. |
|
|
286
|
+
| `tg_list_pixel_events` | read | List or fetch conversion events. |
|
|
287
|
+
| `tg_manage_pixel` | write | Create the pixel, create/rename/delete events. |
|
|
288
|
+
|
|
289
|
+
### Transactions
|
|
290
|
+
|
|
291
|
+
| Tool | Access | Purpose |
|
|
292
|
+
| ---------------------- | ------ | ---------------------------------------------- |
|
|
293
|
+
| `tg_list_transactions` | read | Account-level or ad-level transaction history. |
|
|
294
|
+
| `tg_get_transaction` | read | Status of a budget transaction. |
|
|
295
|
+
|
|
296
|
+
### Advanced
|
|
297
|
+
|
|
298
|
+
| Tool | Access | Purpose |
|
|
299
|
+
| ------------- | ---------- | -------------------------------------------------------------- |
|
|
300
|
+
| `tg_search` | read | Search all official methods by name, description or parameter. |
|
|
301
|
+
| `tg_get_sdk` | read | TypeScript declarations for the Code Mode `tg` namespace. |
|
|
302
|
+
| `tg_execute` | sandboxed | Run JavaScript with sequential API calls in QuickJS. |
|
|
303
|
+
| `tg_api_call` | read/write | Escape hatch for any method without a dedicated tool. |
|
|
304
|
+
|
|
305
|
+
The server also exposes:
|
|
306
|
+
|
|
307
|
+
- **Resources:** `telegram-ads://guide`, `telegram-ads://method-catalog`, `telegram-ads://sdk.d.ts`
|
|
308
|
+
- **Prompts:** `launch-ad`, `audit-account`, `weekly-report`
|
|
309
|
+
|
|
310
|
+
## Code Mode
|
|
311
|
+
|
|
312
|
+
Code Mode lets an agent run one short JavaScript program instead of dozens of tool calls: bulk
|
|
313
|
+
edits, pagination, joins, cross-ad analysis and compact reports.
|
|
314
|
+
|
|
315
|
+
```js
|
|
316
|
+
const ads = await tg.getAdsList({ limit: 100 });
|
|
317
|
+
const active = ads.ads.filter((ad) => ad.status === "active");
|
|
318
|
+
return active
|
|
319
|
+
.sort((a, b) => (b.spent_budget ?? 0) - (a.spent_budget ?? 0))
|
|
320
|
+
.map((ad) => ({
|
|
321
|
+
id: ad.ad_id,
|
|
322
|
+
title: ad.title,
|
|
323
|
+
spent: ad.spent_budget,
|
|
324
|
+
cpm: ad.cpm,
|
|
325
|
+
}));
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
Limits and guarantees:
|
|
329
|
+
|
|
330
|
+
- QuickJS (WebAssembly) sandbox with **no network, filesystem, process or environment access**.
|
|
331
|
+
- Only the `tg` object and `console` are exposed.
|
|
332
|
+
- Calls run **sequentially**, so scripts are deterministic and cannot burst the API.
|
|
333
|
+
- At most **25 API calls**, **15 seconds**, **64 MB** of memory and **64 KB** of output per run.
|
|
334
|
+
- Read-only unless `TG_ADS_MODE=write` **and** `TG_ADS_CODE_MODE=write`, and `tg_execute` is called
|
|
335
|
+
with `confirm: true`.
|
|
336
|
+
|
|
337
|
+
See [docs/code-mode.md](docs/code-mode.md) for examples and the full security model.
|
|
338
|
+
|
|
339
|
+
## CLI
|
|
340
|
+
|
|
341
|
+
```text
|
|
342
|
+
telegram-ads-mcp serve Start the MCP server over stdio (default)
|
|
343
|
+
telegram-ads-mcp doctor Check configuration and verify the token
|
|
344
|
+
telegram-ads-mcp init Write MCP client configuration
|
|
345
|
+
telegram-ads-mcp --version Print the version
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
`init` options:
|
|
349
|
+
|
|
350
|
+
```text
|
|
351
|
+
--client <name...> claude-desktop, cursor, opencode, claude-code, codex, or all
|
|
352
|
+
--token <token> Defaults to TELEGRAM_ADS_TOKEN
|
|
353
|
+
--mode <mode> read-only or write (default: read-only)
|
|
354
|
+
--code-mode <mode> off, read-only or write (default: read-only)
|
|
355
|
+
--local <path> Launch a built local checkout instead of npx
|
|
356
|
+
--github Launch github:furkankoykiran/telegram-ads-mcp instead of the npm package
|
|
357
|
+
--print Print the configuration without writing files
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
The token is stored in plain text in the generated client config. Keep that file private and revoke
|
|
361
|
+
the token at <https://ads.telegram.org/account/api> if it is exposed.
|
|
362
|
+
|
|
363
|
+
## Development
|
|
364
|
+
|
|
365
|
+
```bash
|
|
366
|
+
npm install
|
|
367
|
+
npm run typecheck
|
|
368
|
+
npm run lint
|
|
369
|
+
npm test
|
|
370
|
+
npm run build
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
| Script | Purpose |
|
|
374
|
+
| ---------------------- | --------------------------------------------------------------- |
|
|
375
|
+
| `npm run dev` | Run the CLI from source with `tsx`. |
|
|
376
|
+
| `npm run check` | Typecheck, lint and test in one pass. |
|
|
377
|
+
| `npm run sync-catalog` | Re-parse the official docs and regenerate `src/api/catalog.ts`. |
|
|
378
|
+
| `npm run format` | Format the repository with Prettier. |
|
|
379
|
+
|
|
380
|
+
Project layout:
|
|
381
|
+
|
|
382
|
+
```text
|
|
383
|
+
src/
|
|
384
|
+
api/ Catalog, shared types and the HTTP client
|
|
385
|
+
code-mode/ QuickJS sandbox and generated SDK declarations
|
|
386
|
+
tools/ MCP tool registrations
|
|
387
|
+
cli.ts serve / doctor / init
|
|
388
|
+
server.ts McpServer assembly
|
|
389
|
+
policy.ts Write gates, account allowlist and budget caps
|
|
390
|
+
audit.ts Optional JSONL audit log
|
|
391
|
+
tests/
|
|
392
|
+
unit/ Money, client, policy, sandbox, catalog, schemas
|
|
393
|
+
contract/ End-to-end MCP client/server contract tests
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
The method catalog is generated from <https://ads.telegram.org/docs/api>. If Telegram ships a new
|
|
397
|
+
API revision, run `npm run sync-catalog`, review the diff and update the tools that need new fields.
|
|
398
|
+
Do not edit `src/api/catalog.ts` by hand.
|
|
399
|
+
|
|
400
|
+
## Troubleshooting
|
|
401
|
+
|
|
402
|
+
| Symptom | Fix |
|
|
403
|
+
| --------------------------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
404
|
+
| `UNAUTHORIZED` / HTTP 401 | The token is invalid or revoked. Create a new one at <https://ads.telegram.org/account/api>. |
|
|
405
|
+
| `WRITE_DISABLED` | Set `TG_ADS_MODE=write` in the server environment and restart the client. |
|
|
406
|
+
| `CONFIRMATION_REQUIRED` | Re-run the write with `confirm: true` after checking the parameters. |
|
|
407
|
+
| `CHANNEL_ID_UNKNOWN` / `BOT_ID_UNKNOWN` | Use `@username` first so the account resolves it, then numeric IDs will work. |
|
|
408
|
+
| `IDEMPOTENT_PARAM_MISMATCH` | The key was already used with different parameters. Retry with a new key. |
|
|
409
|
+
| `IDEMPOTENT_REQUEST_IN_PROGRESS` | An identical request is still running. Wait and retry with the same key. |
|
|
410
|
+
| Precision errors | Check the account currency with `tg_get_account`; EUR/TON use 2 decimals for CPM, XTR uses 0. |
|
|
411
|
+
| Stats range error | Use an interval of 300 or 86400 seconds and at most 1000 intervals; the server splits larger ranges. |
|
|
412
|
+
| Client does not see the server | Restart the client after editing its config, and check that `node --version` is 22.18 or newer. |
|
|
413
|
+
|
|
414
|
+
## Security
|
|
415
|
+
|
|
416
|
+
Please read [SECURITY.md](SECURITY.md) before using write mode in production. Report vulnerabilities
|
|
417
|
+
through GitHub's private vulnerability reporting, not in a public issue.
|
|
418
|
+
|
|
419
|
+
## License
|
|
420
|
+
|
|
421
|
+
MIT © Furkan Koykiran. See [LICENSE](LICENSE).
|
package/assets/logo.svg
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512" role="img" aria-labelledby="title">
|
|
2
|
+
<title id="title">Telegram Ads MCP</title>
|
|
3
|
+
<rect width="512" height="512" rx="112" fill="#0B1220"/>
|
|
4
|
+
|
|
5
|
+
<!-- Ascending analytics bars -->
|
|
6
|
+
<g id="analytics-bars">
|
|
7
|
+
<rect x="108" y="318" width="44" height="72" rx="12" fill="#FFB86B"/>
|
|
8
|
+
<rect x="168" y="250" width="44" height="140" rx="12" fill="#FFB86B"/>
|
|
9
|
+
<rect x="228" y="182" width="44" height="208" rx="12" fill="#FFB86B"/>
|
|
10
|
+
</g>
|
|
11
|
+
|
|
12
|
+
<!-- Original origami paper plane -->
|
|
13
|
+
<g id="paper-plane">
|
|
14
|
+
<polygon points="428,92 316,230 254,162" fill="#4EECD0"/>
|
|
15
|
+
<polygon points="428,92 316,230 296,272" fill="#149D7C"/>
|
|
16
|
+
<polygon points="428,92 398,272 316,230" fill="#2DE2B7"/>
|
|
17
|
+
</g>
|
|
18
|
+
</svg>
|
package/dist/cli.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
#!/usr/bin/env node
|