MCP: an AI assistant in the tracker
Starting with version 0.9.5.0 you can connect an AI assistant (Claude Desktop and other MCP clients) to Orbitra through the MCP server โ it lives in the mcp/ folder. Once connected, the tracker can be driven in plain language:
"How did my campaigns do over the last 7 days?"
"Create 10 campaigns for offer #4 โ one per GEO: US, CA, GB, DE, FR."
"Add the domain track.example.com and put campaign 12 on its root."
The server talks to your tracker over HTTPS using a personal API key. It stores nothing on its own side, and read-only keys physically cannot modify data.
How it works
Claude Desktop โโstdioโโโบ mcp/src/index.js โโHTTPS + API keyโโโบ ะฒะฐั Orbitra (api.php)
The MCP server is a thin client over the tracker's regular API (api.php). It simply wraps API actions into tools an AI can understand and adds a safeguard (read keys cannot write).
Step 1. Get an API key
In the panel: โ โ AI / MCP or โ โ Users โ API keys (keys are created by an admin).
- Read key โ analytics only (metrics, lists, reports).
- Write key โ plus management (creating/editing/deleting campaigns, offers, domainsโฆ).
The key is shown once โ copy it.
Step 2. Install dependencies
When installed via install.sh, MCP dependencies are installed automatically. Manually:
cd mcp
npm install
Self-check (starts the server and prints the tool list; no live tracker needed):
npm run smoke
Checking against a live tracker:
ORBITRA_URL=https://tracker.example.com ORBITRA_API_KEY=your_key npm run smoke -- --ping
Step 3. Connect Claude Desktop
The Claude Desktop config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Option A. Remote connection by URL (since version 0.9.6.2)
The fastest option, and the only one that works in the browser version of Claude: the tracker itself serves MCP over HTTP through mcp.php.
- โ โ Users โ API keys, create a key (Read โ analytics only, Write โ plus management).
- Click the link button next to the key โ a ready-made URL is copied to the clipboard:
https://ะฒะฐั-ััะตะบะตั.example.com/mcp.php?k=ะะะจ_ะะะฎะง
- In Claude: Settings โ Connectors โ Add custom connector, paste the URL, set a name, "Add".
Nothing to install โ neither Node nor the repository on your machine.
๐ The key travels right inside the URL, because the connector dialog has no field for a key and only supports OAuth. Treat such a URL as a password: do not publish it, and to cut off access delete the key in โ โ Users โ API keys โ the URL stops working immediately. A read key physically cannot change anything.
How it works. mcp.php implements sessionless MCP Streamable HTTP: every POST is a self-contained JSON-RPC exchange. It takes the tool list from mcp/tools.json, which is generated from the Node server (node mcp/src/manifest.js), so both connection types show exactly the same set of 41 tools. A tool call runs as a short CLI process cli/api_invoke.php โ the tracker does not call itself over HTTP, which on a VPS with two PHP-FPM workers could otherwise block the whole site.
Requirements: PHP CLI (already needed for cron) and proc_open allowed. If proc_open is disabled in php.ini, the endpoint will tell you so in plain text โ use option B in that case. The PHP path can be set manually via the mcp_php_binary setting.
Option B. Local server for Claude Desktop
โ ๏ธ This is not the "Add custom connector" dialog. The Connectors section in Claude only accepts remote MCP servers over HTTPS and authorizes them via OAuth โ that is why there is no API key field there. The Orbitra server runs over stdio: it starts locally next to the assistant and is registered in the config file below. A tracker URL pasted into the connector dialog will not work.
You can open the file right from the app: Settings โ Developer โ Edit Config.
Add an orbitra server (use the absolute path to mcp/src/index.js):
{
"mcpServers": {
"orbitra": {
"command": "/usr/local/bin/node",
"args": ["/absolute/path/to/Orbitra/mcp/src/index.js"],
"env": {
"ORBITRA_URL": "https://tracker.example.com",
"ORBITRA_API_KEY": "ะฒะฐั-api-ะบะปัั"
}
}
}
}
Fully restart Claude Desktop (โQ on macOS) โ the Orbitra tools will appear in the list. Closing the window is not enough; the config is read only at startup.
If the server does not appear:
- Node path.
commandneeds an absolute path: the app does not start from your shell, so Node from nvm or Homebrew never reaches itsPATHand the server silently fails to start. Find the path withwhich node(macOS/Linux) orwhere node(Windows). - Dependencies not installed.
cd mcp && npm install. - Wrong key or URL. Verify separately:
ORBITRA_URL=... ORBITRA_API_KEY=... npm run smoke -- --ping. 403 API key is read-onlyon create or update โ you need a Write key; a Read key only returns analytics.
Tools (41)
Read: orbitra_ping, orbitra_get_metrics, orbitra_get_chart, orbitra_list_campaigns, orbitra_campaigns_stats, orbitra_get_campaign, orbitra_campaign_report, orbitra_list_offers, orbitra_get_offer, orbitra_all_offers, orbitra_list_domains, orbitra_ssl_environment, orbitra_get_integration_code, orbitra_list_app_configs, orbitra_telegram_status, orbitra_integrations_status, orbitra_list_traffic_sources, orbitra_list_landings, orbitra_list_affiliate_networks, orbitra_list_conversions, orbitra_recent_clicks, orbitra_system_status.
Management (requires a write key): orbitra_create_campaign, orbitra_update_campaign, orbitra_bulk_create_campaigns, orbitra_bulk_set_campaign_domain, orbitra_delete_campaign, orbitra_copy_campaign, orbitra_create_offer, orbitra_update_offer, orbitra_delete_offer, orbitra_create_domain, orbitra_delete_domain, orbitra_check_domain_dns, orbitra_reissue_ssl, orbitra_run_ssl_worker, orbitra_save_app_config, orbitra_create_traffic_source, orbitra_list_traffic_source_templates, orbitra_create_landing.
Advanced: orbitra_api_request โ call any api.php action directly (the fallback option).
Large accounts. orbitra_list_campaigns and orbitra_list_domains return compact lists (id, name, alias, domain, link) with ID-range and domain filters and pagination โ the response stays small even with thousands of campaigns. Stats for all campaigns come from orbitra_campaigns_stats (a heavy response), for a single one โ orbitra_campaign_report. To change the domain of many campaigns at once โ orbitra_bulk_set_campaign_domain: only the domain changes, streams and postbacks are untouched, and the response carries each campaign's old and new link. orbitra_update_campaign preserves stream IDs, their names, filter logic, offer selection and Bot Challenge.
A full parameter reference lives in mcp/README.md.
Security
- Treat the API key like a password. Use a read key by default; write only
when management is needed.
- The key goes only to your
ORBITRA_URL(Authorization: Bearer/X-Api-Keyheaders). - Write actions go through the regular API and land in the audit logs like any other operation.
- A read key gets a
403on write attempts and changes nothing. ORBITRA_INSECURE=1disables TLS verification โ for local development only.
Updates
MCP ships with the project, so the regular update (โ โ Update or git pull) pulls the new files automatically. After an update that changed dependencies, run cd mcp && npm install. If the tool list changed in the new version, reconnect the connector in the client so it re-reads the tools.
Quick start: your first campaign
The short path: install the tracker, create a campaign, and get your first clicks and conversions in under an hour.
Read guide โDocsInstallation and updates
Install Orbitra on a fresh Ubuntu or Debian server with one command, and update to new versions safely.
Read guide โDocsMigrating from Keitaro
Move campaigns, offers, sources and domains from Keitaro to Orbitra in one click โ what transfers and what to check.
Read guide โDocsMigrating from Binom
Move campaigns and streams from Binom to Orbitra: what transfers automatically and what to set up by hand.
Read guide โDocsFeature overview
Everything Orbitra can do: campaigns and streams, cloaking, landings, PWA, postbacks, costs, reports and integrations.
Read guide โDocsCampaigns and streams
The complete reference: campaign settings, stream types, schemas, rotation, filters, test links and every option explained.
Read guide โDocsCloaking
Full cloaking reference: detection layers, global settings, per-stream filters, verdicts and reports.
Read guide โDocsBrowser check
How the JS check catches bots, VMs and emulators through contradictions in the browser environment.
Read guide โDocsLanding pages
Landing types, the {offer} macro, the JS adapter, LeadForge and multi-offer landings โ the complete reference.
Read guide โDocsPWA and Web Push
Build installable PWA apps and collect push subscribers: settings, icons, events and notifications.
Read guide โDocsPWA Funnel
A multi-step PWA funnel: install prompts, event tracking and re-engagement notifications.
Read guide โDocsConversion popups
Show real conversion events as on-page popups: setup, triggers and placement.
Read guide โDocsSession recordings and heatmaps
Replay real visits and see click and scroll maps. Storage limits and privacy notes.
Read guide โDocsContent gallery
Central storage for icons, screenshots and creatives used across PWAs and landings.
Read guide โDocsCreatives library
Store creatives with subid tracking and test them across campaigns.
Read guide โDocsExternal PWA and Telegram channels
Publish PWAs to external domains and run Telegram channels as a traffic source.
Read guide โDocsPostbacks and conversions
Incoming postbacks, conversion statuses and types, and outgoing S2S postbacks to your traffic source.
Read guide โDocsCosts
Import spend from Facebook, TikTok and Google Ads, or update it via API and cron โ and how the revenue aggregator works.
Read guide โDocsPush and pop networks
Working with push and pop traffic sources: feeds, zone optimization and the zone killer.
Read guide โDocsFacebook / Meta
Cost import from Meta Ads and the Conversions API: server-side events with deduplication.
Read guide โDocsDolphin / Fbtool
Receive Facebook costs through the Dolphin (Fbtool) API in real time.
Read guide โDocsFB comment cleaner
Bulk-moderate comments under Meta ads: hide, delete and filter by keywords.
Read guide โDocsTraffic sources and affiliate networks
Catalog of 50+ traffic sources and 440+ networks: templates, parameters and postback URLs.
Read guide โDocsReports, logs and metrics
The report builder, saved reports, click logs and every metric explained.
Read guide โDocsDomains and SSL
Add domains, DNS, free Let's Encrypt certificates, redirects, parking and every switch on the page.
Read guide โDocsCloudflare
How to run campaign domains through Cloudflare: DNS, SSL modes and what to turn off.
Read guide โDocsAdministration
Users, roles and permissions, security settings, geo databases, updates and system health.
Read guide โDocsTelegram bot
Manage the tracker from Telegram: stats, conversions and alerts in chat.
Read guide โDocsMCP: an AI assistant in the tracker
Connect Claude or any MCP client to Orbitra and manage campaigns with plain-language commands.
Read guide โ