Telegram Ads MCP
Provides tools for managing Telegram Ads through the official Telegram Ads API, including accounts, advertisements, budgets, statistics, audiences, pixels, and targeting, with read-only/write modes and safety controls.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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
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 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 doctorAfter the npm release, the shorter form works too:
npx -y telegram-ads-mcp doctorOr build a local checkout:
git clone https://github.com/furkankoykiran/telegram-ads-mcp.git
cd telegram-ads-mcp
npm install
node dist/cli.js doctordoctor 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-mcp3. Ask your agent to start
Restart the client and ask:
Use
tg_get_accountto show my Telegram Ads account and currency.
Then try a read-only report:
Use
tg_get_statsfor 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 |
| required | API token from https://ads.telegram.org/account/api. |
| — | Alias for |
|
|
|
|
|
|
| all | Comma-separated allowlist for explicit |
| no cap | Maximum CPM accepted by the server, in account currency. |
| no cap | Maximum ad budget or budget transfer per call. |
| no cap | Maximum daily budget limit per call. |
| disabled | Path to a JSONL audit log. Parent directories are created. |
|
| Per-request timeout in milliseconds. |
| 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.
Read-only by default.
TG_ADS_MODEdefaults toread-only. Every write tool fails before it reaches the API.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.New ads start paused with zero budget.
tg_create_addefaultsis_pausedtotrueandinitial_budgetto0. Funding is a separate, explicit step.Dry runs.
tg_create_adandtg_update_adacceptdry_run: trueto show the exact payload and currency without calling the API.Account allowlist.
TG_ADS_ALLOWED_ACCOUNTSrejects explicitaccount_idvalues outside the list.Budget caps.
TG_ADS_MAX_CPM,TG_ADS_MAX_AD_BUDGETandTG_ADS_MAX_DAILY_BUDGETreject oversized values before the request is sent.Idempotency. Every write carries an
Idempotency-Key; retries reuse the same key. Tools accept an explicit key when the caller needs to retry safely.Audit log. Set
TG_ADS_AUDIT_LOGto keep a JSONL record of tool calls. Phone numbers, emails and legal names are summarized, and ad text/code is reduced to its length.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 |
| read | Current account, currency, budgets. Optionally list related accounts. |
| read | Billing/profile details (company, email, phone, country, city). |
| write | Increase or decrease a related account's budget. |
Advertisements
Tool | Access | Purpose |
| read | Paged ad list with status, budgets and lifetime metrics. |
| read | Up to 100 ads by ID, including decline reasons. |
| write | Create a paused, zero-budget ad. Supports |
| write | Edit fields, pause/resume, or submit for review. Supports |
| write | Move funds into or out of an ad. |
| write | Delete an inactive ad with no remaining budget. |
| write | Upload ad photos, videos or website photos from a local path. |
Statistics
Tool | Access | Purpose |
| read | Account or per-ad stats, with totals and CTR/CPM/CPC. |
| read | Telegram's monthly account report. |
Targeting
Tool | Access | Purpose |
| read | Languages, topics, countries, locations, channels and bots. |
Audiences and pixels
Tool | Access | Purpose |
| read | List or fetch retargeting audiences. |
| write | Create, edit or delete a phone-number audience. |
| read | Pixel ID and installation snippet. |
| read | List or fetch conversion events. |
| write | Create the pixel, create/rename/delete events. |
Transactions
Tool | Access | Purpose |
| read | Account-level or ad-level transaction history. |
| read | Status of a budget transaction. |
Advanced
Tool | Access | Purpose |
| read | Search all official methods by name, description or parameter. |
| read | TypeScript declarations for the Code Mode |
| sandboxed | Run JavaScript with sequential API calls in QuickJS. |
| 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.tsPrompts:
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
tgobject andconsoleare 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=writeandTG_ADS_CODE_MODE=write, andtg_executeis called withconfirm: 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 versioninit 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 filesThe 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 buildScript | Purpose |
| Run the CLI from source with |
| Typecheck, lint and test in one pass. |
| Re-parse the official docs and regenerate |
| 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 testsThe 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 |
| The token is invalid or revoked. Create a new one at https://ads.telegram.org/account/api. |
| Set |
| Re-run the write with |
| Use |
| The key was already used with different parameters. Retry with a new key. |
| An identical request is still running. Wait and retry with the same key. |
Precision errors | Check the account currency with |
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 |
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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Multi-tenant Telegram gateway for AI agents — HTTP+stdio, 8 tools, MTProto User API
Open-source ad agent for LinkedIn Ads and Google Ads. Drafts campaigns, audiences and reports.
The simplest way to manage your Meta (Facebook and Instagram) ad accounts with your AI agent.
Telegram ad exchange: estimate reach and cost with no account, then create and run campaigns.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn 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.111MIT
- FlicenseAqualityBmaintenanceEnables 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.264-
- AlicenseNot gradedqualityBmaintenanceEnables 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.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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