tgtrack-mcp
tgtrack-mcp lets an AI agent manage a tgtrack / «Откуда Подписки» account (channels, ad-system integrations, tracking-script settings, goals, links, reports) through the panel's internal, JWT-signed API — no official API required.
Channels (read): list all channels/groups/bots (
tgtrack_list_channels); get full channel detail — integrations, links, script and report settings (tgtrack_get_channel).Integrations ("ad systems"): create one (
tgtrack_create_integration, incl. Yandex OAuthgrantAccessUrl+webCreationCode); poll Yandex auto-goal creation (tgtrack_yandex_web_create_status); get the Yandex re-grant link (tgtrack_get_restore_yandex_link).Script & goals: change script settings — strict mode, conversion delay, auto-approve, goal flags,
trackThroughWebApp(tgtrack_set_script_settings); update/create goals name & value (tgtrack_update_goal).Links & landings: list landings (
tgtrack_get_landings); set a link's target URL (tgtrack_set_link_url); rename a link/integration (tgtrack_set_link_name); configure under-post button links (tgtrack_set_outbound_link_params); build a ready landing<script>+ click link offline (tgtrack_get_integration_script).Channel controls: toggle join-request auto-approval (
tgtrack_set_channel_auto_approve); configure daily reports — morning report, send-if-no-subs, traffic report (tgtrack_set_report_settings).Destructive (gated behind
confirm: true, otherwise only describe what they would do): delete an invite link/integration (tgtrack_delete_invite_link), delete an outbound link (tgtrack_delete_outbound_link), mint a new API key invalidating the old one (tgtrack_new_api_token), mint a new report key (tgtrack_new_report_key).Not available: analytics reports over time (planned v2), admin tools (planned v1.1), and the runtime Bot API tools documented in the README (
tgtrack_bot_*— events, deep goals,get_user_info) are absent from this schema. Auth is via a short-livedTGTRACK_TOKENJWT; the server also supports stdio and streamable HTTP transports.
Manages Telegram channels and tracks subscriber sources, with tools for channel management, integration with advertising systems, and tracking script configuration.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tgtrack-mcp list my channels"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
tgtrack-mcp
Manage a tgtrack / «Откуда Подписки» account from an AI agent — channels, ad-system integrations, tracking-script settings, goals and links — with no official API.
English · Русский
Why
tgtrack ("Откуда Подписки") tracks where your Telegram subscribers come from and feeds offline "subscription" conversions back to Yandex Metrika / Direct. All of it — channels, "advertising systems" (integrations), the landing tracking-script, goals, links, daily reports — lives only in the settings.tgtrack.ru panel. There is no public API.
tgtrack-mcp exposes that control plane as MCP tools. It talks to the same internal endpoints the panel uses and signs every request exactly like the panel does (a short-lived JWT plus an md5-based request signature), so an AI agent (Claude, etc.) can list channels, read and create integrations, tweak the script settings, goals and links — in one turn.
🔑 Uses your panel token — a JWT read from the
settings.tgtrack.ruURL; nothing is scraped or hardcoded🧩 26 focused tools — the settings control plane plus the runtime Bot API (start/stop events, deep goals,
get_user_info); read + safe writes, destructive actions gated behindconfirm: true🧮 Panel-accurate signing —
H = md5(md5(JSON + T) + T), verified against a live sample🪶 TypeScript, ESM, strict — thin, MIT, no account secrets in the repo
Related MCP server: telegram-ads
How it works
Every call is a POST to https://api.tgtrack.ru/API/settings/<endpoint>.php with a multipart/form-data body of two fields:
JSON = JSON.stringify({ ...params, T, tn }) // T = unix seconds, tn = your JWT
H = md5( md5(JSON + T) + T ) // request signature (T is the salt)The response is a { S, D, M } envelope: S === 0 means success and the payload is D.data; otherwise the tool returns a typed error (217/218 = bad/expired token → a clear "refresh your token" message).
Requirements
Node ≥ 18.
A tgtrack token (
TGTRACK_TOKEN): open settings.tgtrack.ru, and copy thet=value from the address bar (or thetgtrack_tokencookie). It is short-lived (~72 h); tgtrack has no working refresh endpoint, so re-paste it when it expires.
Setup
npm install
npm run buildRegister it with your MCP client (see .mcp.json.example):
{
"mcpServers": {
"tgtrack": {
"command": "node",
"args": ["dist/index.js"],
"env": { "TGTRACK_TOKEN": "<the ?t=... JWT from settings.tgtrack.ru>" }
}
}
}Tools
Read
Tool | Purpose |
| List all channels / groups / bots on the account. |
| Full channel: integrations (ad systems), links, script & report settings. |
| Build the ready |
Integrations ("advertising systems")
Tool | Purpose |
| Create an integration. For |
| Script settings of an integration (strict mode, conversion delay, auto-approve, goal flags…). |
| Update a goal (name/value in Metrika), optionally create it. |
| Poll Yandex auto-goal creation by |
| Link to re-grant Yandex access for an integration. |
Links & channel
Tool | Purpose |
| Landings attached to a channel / integration. |
| Change a link's target URL. |
| Rename a link / integration. |
| Params of an under-post button link (target, button text, subscription check). |
| Toggle auto-approval of join requests. |
| Daily-report toggles (morning report, send-if-no-subs, traffic report). |
Dangerous — require confirm: true
Tool | Purpose |
| ⚠️ Delete an invite link / integration (irreversible). |
| ⚠️ Delete an outbound link (irreversible). |
| ⚠️ Mint a new API key — invalidates the previous one. |
| ⚠️ Mint a new report key — invalidates the previous one. |
Without confirm: true the dangerous tools return a description of what they would do and never touch the API.
Bot API — runtime events (bot-api.tgtrack.ru)
A second contour, separate from the settings API: it is not JWT-signed — it POSTs JSON to
https://bot-api.tgtrack.ru/v1/<API_KEY>/<method> (MAX: https://max.tgtrack.ru/API/bot-api/v1/<API_KEY>/<method>).
The API_KEY is the per-bot/channel key (apiToken in tgtrack_get_channel), not the panel JWT —
pass it as apiKey on each call, or set TGTRACK_BOT_API_KEY. Add max: true for MAX.
Tool | Purpose |
| Build the webhook URL for a constructor (e.g. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Usage
Run the MCP server over stdio, or call a tool directly for scripting:
node dist/index.js # MCP (stdio)
TGTRACK_TOKEN=... npx tsx src/run.ts tgtrack_list_channels
TGTRACK_TOKEN=... npx tsx src/run.ts tgtrack_get_channel '{"chatID":"600334c8b9b9e"}'
TGTRACK_TOKEN=... npx tsx src/run.ts tgtrack_get_integration_script \
'{"linkID":"5cd4255d831d9e","counterID":"110494105"}'
# Bot API (per-bot key, no JWT):
npx tsx src/run.ts tgtrack_bot_event_url '{"apiKey":"<API_KEY>","method":"my_bothelp_was_started"}'
npx tsx src/run.ts tgtrack_bot_get_user_info '{"apiKey":"<API_KEY>","userId":"123456789"}'Streamable HTTP transport:
TGTRACK_TOKEN=... node dist/index.js --http --port 3001 # /mcp, /healthScope
Included: the full settings/management control plane — channels, integrations, script settings, goals, links, reports — and the runtime Bot API (start/stop events, deep goals, add_event, get_user_info).
Not included yet:
Analytics reports (subscribers over time, source breakdown, conversions) — this lives behind a separate reporting API keyed by a report key (
tgtrack_new_report_key). Planned for v2.Admin tools (
deleteChannel,changeUserAccess, …) — planned behind a flag (v1.1).MAX (
max.tgtrack.ru) parity — behind aserviceoption.
Security
The token lives only in your environment (TGTRACK_TOKEN) — never in the repo, never logged, never echoed in error messages. .mcp.json and .env are git-ignored; only .mcp.json.example (with a placeholder) is committed.
Contributing
Contributions welcome — open an issue or a PR.
Fork and branch:
git checkout -b feature/my-changenpm install;npm run buildandnpm testmust passNever commit secrets (the JWT /
.env/ a real.mcp.json) or real account dataOpen a PR describing what and why
License
MIT
Available Tools
18 toolstgtrack_create_integrationA
Создать интеграцию («рекламную систему»). Для yandex вернёт grantAccessUrl + webCreationCode (нужно завершить OAuth в браузере).
Inputs: chatID (required), linkName (required), accessToken, counterNumber, +9 more.
tgtrack_delete_invite_linkA
⚠️ Удалить invite-ссылку/интеграцию (необратимо). Требует confirm:true.
Inputs: chatID (required), linkID (required), confirm.
tgtrack_delete_outbound_linkA
⚠️ Удалить outbound-ссылку (необратимо). Требует confirm:true.
Inputs: chatID (required), linkID (required), confirm.
tgtrack_get_channelA
Полная инфа по каналу: интеграции (рекламные системы), ссылки, настройки скрипта и отчётов.
Inputs: chatID (required).
tgtrack_get_integration_scriptA
Собрать готовый landing-скрипт + click-ссылку по linkID и counterID (без запроса к API).
Inputs: linkID (required), counterID (required).
tgtrack_get_landingsC
Лендинги, привязанные к каналу/интеграции.
Inputs: chatID (required), linkID.
tgtrack_get_restore_yandex_linkC
Ссылка для восстановления/повторной выдачи Яндекс-доступа по интеграции.
Inputs: linkID (required).
tgtrack_list_channelsB
Список всех каналов/групп/ботов пользователя в tgtrack.
Inputs: no named parameters.
tgtrack_new_api_tokenA
⚠️ Создать новый API-ключ канала — ИНВАЛИДИРУЕТ предыдущий. Требует confirm:true.
Inputs: chatID (required), confirm.
tgtrack_new_report_keyA
⚠️ Создать новый ключ отчётов — инвалидирует предыдущий. Требует confirm:true.
Inputs: chatID (required), confirm.
tgtrack_set_channel_auto_approveB
Вкл/выкл авто-одобрение заявок на вступление в канал.
Inputs: chatID (required), autoApprove (required).
tgtrack_set_link_nameC
Переименовать ссылку/интеграцию.
Inputs: name (required), chatID (required), linkID (required), isOutbound.
tgtrack_set_link_urlC
Изменить целевой URL ссылки (targetUrl).
Inputs: chatID (required), linkID (required), targetUrl (required).
tgtrack_set_outbound_link_paramsC
Параметры outbound-ссылки (кнопка под постом): targetUrl, текст кнопки, проверка подписки.
Inputs: linkID (required), targetUrl (required), buttonText, unsubscribedText, +1 more.
tgtrack_set_report_settingsC
Настройки ежедневных отчётов канала (утренний отчёт, если нет подписок, отчёты по трафику).
Inputs: chatID (required), sendIfNoSubs, sendMorningReport, sendTrafficReport.
tgtrack_set_script_settingsC
Изменить настройки скрипта интеграции (strictMode, conversionDelay, авто-одобрение, флаги целей и т.п.).
Inputs: chatID (required), linkID (required), strictMode, autoApprove, +6 more.
tgtrack_update_goalB
Обновить цель интеграции (имя/значение цели в Метрике), опционально создать её.
Inputs: chatID (required), linkID (required), goalName (required), goalValue (required), +1 more.
tgtrack_yandex_web_create_statusB
Статус авто-создания целей в Яндексе по webCreationCode из create_integration.
Inputs: chatID (required), webCreationCode (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Each tool targets a distinct resource or action (e.g., create integration, delete link, get channel info), with no overlapping purposes. Descriptions further clarify unique roles.
All tools follow a consistent 'tgtrack_verb_noun' pattern using snake_case, with verbs like create, delete, get, list, set, new, update. Only minor variation like 'new' vs 'create' but pattern is uniform.
18 tools is well-scoped for managing integrations, channels, links, reports, and settings. Not excessive, and each tool serves a clear purpose within the domain.
The set covers CRUD-like operations for integrations, links, channels, and settings, plus specialized actions for Yandex OAuth, script generation, and goal updates. No obvious gaps for the server's scope.
Maintenance
Related MCP Connectors
SEO & marketing toolkit for AI agents: GA4, Search Console, AdSense, GTM, PageSpeed, Trends.
Short-link service embedded in your AI workflow — shorten links, track campaigns, read stats.
Privacy-first, cookie-free web analytics. Read stats and manage sites from your AI.
MCP for Yandex Direct: manage ad campaigns & analytics from Claude or ChatGPT
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
- AlicenseNot gradedqualityBmaintenanceProvides typed tools for ads.telegram.org, enabling login via Playwright and a read-only watcher through a local stdio MCP server.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to work with Yandex Webmaster, Direct, and Metrika data through natural language, including managing sites, sitemaps, recrawls, ad campaigns with write-safety guards, and pulling traffic, conversion, and ad statistics.MIT
- 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-