Affiliate MCP Server

affiliate-mcp

Integrate your affiliate networks with Claude or Codex.

Network operators: most adapters are community-built and experimental. Adoption gives your team ownership and a verification path; promotion to partial or production still requires current evidence and maintainer review. Find your network's issue under the adopt-this-network label.

Affiliate networks have two sides — and neither has a first-class AI workspace integration.

Publishers earn commissions from the programmes they join. Brands (and the agencies who manage them) run those programmes and pay the commissions out. I wanted to chat to my own affiliate data in the AI workspace I already use; none of the networks had shipped an integration for either side, so I built a broad beta set that covers both publisher and advertiser-side work.

If you're a publisher, you can ask:

"What did I earn across all networks last month?"

"Which programmes have transactions still pending after 90 days?"

"Compare my earnings month on month."

If you're on the brand side — running a programme, or an agency managing several — you can ask:

"How is Acme's programme doing this quarter?"

"Show me revenue across all my clients this week."

"Any anomalies in the affiliate data?"

Your AI workspace figures out which networks to call, fetches the data live from their APIs, and gives you the answer. You can use Claude or Codex to turn it into a sheet, an artifact, an email to your boss, whatever you want.

Free and open source. MIT licensed. Bring your own keys. For the product philosophy, read the AI-native affiliate data manifesto.

Who this is for

This tool serves two audiences. Pick the one that fits — or both, if you wear both hats.

You're a publisher. You earn commissions from affiliate programmes, your dashboards can't keep up with how fast you can think, and you want one conversation that spans every network you're on.

You're on the brand side. You run an affiliate programme — or you're an agency managing several brands' programmes. You want one question that fans out across networks and brands, and surfaces what the dashboards bury: publishers trending down, reversal spikes, dead links, programmes drifting toward zero.

Either way, you do not need to know what an API is or write code. The non-technical Claude Desktop track needs:

• Your existing logins to the affiliate networks you already work with.
• Claude Desktop installed.

The technical track uses a terminal, Node.js 20 or newer, and Claude Desktop, Claude Code, Codex, or another compatible local stdio MCP client; check the support states below before relying on an untested client journey.

And if you work for an affiliate network, this is also for you. The bundled adapters are placeholders until each network adopts its own. See CONTRIBUTING.md under "Adopting your network".

Why bother?

One question, every network and every brand. "Show me earnings by programme" hits your configured publisher networks in parallel. On the brand side, "show me revenue across all my clients this week" fans out across every brand and network pair you've registered.

Plain English, not filters. No more clicking through date pickers and saved views. "Last quarter, status pending, sorted by amount" is the whole prompt.

Your data, your machine, by default. It runs locally. Your keys live in ~/.affiliate-mcp/.env, locked to your user account. Optional anonymous usage telemetry is off by default and never contains affiliate data, credentials, prompts, arguments, results, or error text. The networks see the same API calls they'd see from their dashboard.

Catches what dashboards bury. Stale transactions, inactive programmes, dead deeplinks and week-on-week drops are surfaced by the packaged skills.

Optional local result cache. Persistent caching is off by default. Set AFFILIATE_MCP_CACHE=on in ~/.affiliate-mcp/.env to cache selected programme inventory and closed reporting windows locally with owner-only permissions. Open and current windows always go live. On a shared machine where you cannot rely on file permissions, leave caching off. Run affiliate-networks-mcp cache clear to remove cached results; see PRIVACY.md for the storage and retention contract.

Getting started

Choose one of two primary tracks. Both run the same local MCP server and keep your credentials on your machine.

Track 1: non-technical, Claude Desktop

Use the host-native Claude Desktop .mcpb. No Terminal, Node.js, or manual configuration is required.

1. Download affiliate-networks-mcp-<version>.mcpb from the latest GitHub release.
2. In Claude Desktop, open Settings → Extensions → Advanced settings → Install Extension… and select the downloaded file.
3. Add credentials for the networks you use, then ask Claude "What affiliate networks do you have access to?"

The extension does not update itself: download the latest .mcpb and install it over the top; saved credentials are kept (full steps for every install path). The native extension currently offers secure setup fields for Awin, CJ, Impact, and Partnerize. It runs the complete server, so an existing ~/.affiliate-mcp/.env continues to enable every other adapter. A portable browser setup flow for the remaining networks is planned; until then, use the technical track below when adding them.

The standalone Electron/DMG setup app is a fixes-only compatibility fallback for existing macOS users. It is not a third primary onboarding track. See desktop/README.md for its remaining use case.

Track 2: technical and semi-technical, CLI plus local stdio

You'll need Node.js 20 or newer installed. If you don't have it, use the Node.js download page.

1. Run the setup wizard. Open Terminal (macOS) or PowerShell (Windows):

npx affiliate-networks-mcp setup

It walks you through one network at a time, asks which side you want, shows where to find each credential, then checks it against the live network.

For brand-side networks, the wizard asks which brands those credentials can reach, then lets you pick local nicknames. The mapping is saved to ~/.affiliate-mcp/brands.json, see Managing brands.

2. Check everything is wired up.

npx affiliate-networks-mcp test

You should see one line per network: ok for everything that's healthy, error — <reason> for anything that isn't.

3. Connect it to your local MCP client. Use a host-native package, the CLI installer, or local stdio configuration. The setup wizard offers the shipped CLI installer targets at the end automatically.

Claude Desktop (Mac/Windows app):

npx affiliate-networks-mcp install

Finds your Claude Desktop config, adds the affiliate entry alongside anything else you already have, takes a timestamped backup first. Restart Claude Desktop after it finishes. Flags: --desktop / --code / --codex to pick one, --all to include Codex and skip prompting, --dry-run to preview, --force-overwrite if your existing config is malformed JSON.

Claude Code (terminal):

claude plugin marketplace add bobberrisford/affiliatemcp
claude plugin install affiliate-networks-mcp@affiliatemcp

Registers the MCP server and bundled skills in one step. (Or use the install command above — it detects Claude Code too.) Already inside a Claude Code session? Just ask it to install the affiliate-mcp plugin and it runs these commands for you; no terminal juggling needed.

Codex (OpenAI, terminal or IDE extension):

npx affiliate-networks-mcp install --codex

This adds the local stdio MCP server to ~/.codex/config.toml; the same MCP config is used by the Codex CLI and Codex IDE extension. Manual setup:

codex mcp add affiliate -- npx -y affiliate-networks-mcp

Verify: open Codex, run /mcp, then ask "What affiliate networks do you have access to?" This is OpenAI/Codex support, not ChatGPT connector support. ChatGPT requires a reachable HTTPS MCP server and is scoped separately.

Claude Cowork desktop (org accounts):

Cowork syncs plugins from a GitHub repo, but blocks public repos from org marketplaces — so you need a private mirror first. The setup wizard offers this at the end, or run install and pick Cowork:

npx affiliate-networks-mcp install      # detects your clients, offers Cowork

(Or go straight to it: npx affiliate-networks-mcp cowork-mirror.)

It creates <you>/affiliatemcp-internal as a private repo and mirrors the upstream into it. If you have the GitHub CLI (gh) signed in, it's used automatically; otherwise it tells you exactly where to get a GitHub token and prompts you to paste it — the same "paste a credential" flow as setting up a network. Re-run with --sync to refresh against new releases.

Then, with org-admin access, in Cowork: Organization settings → Plugins → Add plugin → GitHub → enter <you>/affiliatemcp-internal → install affiliate-networks-mcp from the synced marketplace.

Open the Claude Desktop config file at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the affiliate entry inside mcpServers — keep any siblings:

{
  "mcpServers": {
    "affiliate": {
      "command": "npx",
      "args": ["affiliate-networks-mcp"]
    }
  }
}

Restart Claude Desktop after saving.

For another local stdio MCP client, configure the server command npx -y affiliate-networks-mcp. These clients are compatible in principle, not yet tested first-party journeys. Draft PR #49 is the existing VS Code/Copilot installer candidate.

Client support states

These labels describe the onboarding journey, not whether every network adapter is live-verified. "Tested" means repository-owned automated validation, not live proof against every host version. See REPORT.md for maturity.

Check it worked. In a new Claude conversation, ask "What affiliate networks do you have access to?" — you should see every network you configured. If you registered any brands, also try "list my brands".

To disconnect later: npx affiliate-networks-mcp uninstall, or claude plugin uninstall affiliate-networks-mcp for the plugin path.

Anonymous telemetry

The project reads aggregate npm and GitHub adoption statistics. npm downloads are downloads, not users: they include repeated npx runs, CI, caches, and other automated traffic.

Optional runtime telemetry is explicitly opt-in and sent at most once per active day. It contains package version, launch surface, a random identifier that rotates monthly, and counts by network, operation, and coarse outcome. See the privacy policy for the exact contract.

affiliate-networks-mcp telemetry status
affiliate-networks-mcp telemetry enable
affiliate-networks-mcp telemetry disable

Troubleshooting install

"Unknown skill: plugin" in a Claude session. The /plugin syntax is a shell command, not a chat slash command. Run claude plugin marketplace add ... from your terminal, not inside the conversation.

Cowork rejects the marketplace repo. Confirm the repo is private. Public repos are blocked for org-marketplace sync. Run npx affiliate-networks-mcp cowork-mirror to create a private mirror.

What affiliate networks… returns nothing. The MCP server is loaded but credentials are missing. Trigger the bundled affiliate-network-setup-help skill (ask "help me set up my affiliate network credentials") or run npx affiliate-networks-mcp setup in a terminal.

Stale npm cache. npx --yes affiliate-networks-mcp@latest forces a fresh fetch. Verify the published version with npm view affiliate-networks-mcp version.

What you can ask

The packaged skills are pre-written conversation patterns. You don't need to invoke them — Claude picks the right one based on what you type.

Publisher side

• "What did I earn last month?" — consolidated earnings report across every publisher network, split by status (pending, approved, paid, reversed), with anything unpaid >90 days flagged.
• "Are all my affiliate networks healthy?" — one-shot auth and capability check.
• "Help me set up Awin" (or CJ, Impact, Rakuten) — guided credential setup with dashboard menu paths quoted verbatim.
• "Audit the affiliate links in my sitemap at https://mysite.com/sitemap.xml" — reads the sitemap, classifies every affiliate link by network, and flags the dead or declined ones. URLs, HTML, or markdown also accepted directly.

Brand side

• "How is Acme performing this quarter?" — single-brand report across that brand's bound networks. Top publishers, status splits, period-over-period delta.
• "Show me revenue across all my clients this week." — portfolio rollup, brand-aggregated, with a "needs attention" subsection for brands trending down.
• "Any anomalies in the affiliate data this week?" — week-over-week scan for revenue drops, reversal spikes, top-10 dropouts, dead programmes. Designed to run on a schedule via Claude's own scheduling.
• "Set up Acme's strategy and KPIs" — bind the brand during setup, record advisory context with client-onboarding, then reports, anomaly watches, and portfolio rollups use it to frame verdicts. It never authorises a network write or changes the figures.

Networks

The repository currently ships 86 adapters across 72 network families. The breadth is real, but maturity varies; most adapters are experimental. Check the table below and REPORT.md before relying on one for production work.

A few networks make you wait for approval (eBay, Rakuten) before they hand over API access. The setup wizard tells you exactly what to do in each case. "Supported ops" being less than 7/7 just means the network itself doesn't expose that data to its users — not a missing feature on our side.

The (advertiser) rows are the brand-side adapters. They use a separate credential type from the publisher row (sometimes the same auth model with a different account behind it; the per-network notes spell out which), and the brand-id is selected per call rather than baked into the credential. Every brand-side adapter is read-only at v0.1 — the client refuses any non-GET HTTP method before it leaves your machine. The full editorial position, including known upstream quirks and the read-only stance, lives in REPORT.md.

Contribute in 10 minutes

A first PR shouldn't take longer than an evening. The path:

1. Pick an issue. Browse the good-first-pr queue. Each has a file path, acceptance bullets, and a how-to-test line. Comment to claim it.

2. Get to green. One command runs the full pre-PR check — typecheck, lint, tests, build — in a few seconds:

   git clone https://github.com/bobberrisford/affiliatemcp.git
   cd affiliatemcp
   npm install
   npm run verify
   

   If npm run verify passes locally, CI will pass.

3. Open the PR. Use the default template (a short summary + test plan). First review within 24h on weekdays — see CONTRIBUTING.md for the full PR process and the four ranked help-wanted areas.

If you work for an affiliate network, the highest-leverage contribution is adopting your own adapter — see the adopt-this-network issues.

Wanted

Networks people have asked for but that don't have an adapter yet. If you work for one of these — or just have API access and want to contribute — this is the most useful place to start. See CONTRIBUTING.md for the workflow, and open (or pile onto) a tracking issue before you start.

Awin reference implementation

Awin is the current reference slice for the repo's future shape. It keeps the seven canonical publisher tools and adds Awin-specific tools for accounts, programme details, commission groups, transaction-by-ID lookup, transaction queries, advertiser/creative/campaign reports, Link Builder, Offers, and safe stubs for gated Product Feed and Proof of Purchase APIs.

Start here if you want to understand the product direction:

• AI-native affiliate data rationale
• Awin public API inventory
• Awin setup and live validation notes

Where your credentials live

When you run the setup wizard it writes a single file at ~/.affiliate-mcp/.env on your machine, locked to your user account (file mode 0600). That's the only place your API keys exist outside the network dashboards. Both publisher and brand-side credentials live here, each keyed by network slug; open, edit, delete, or copy it like any other file.

If you registered any brand-side networks, the wizard also writes ~/.affiliate-mcp/brands.json next to it, mapping your local nickname for each brand (e.g. acme) to the network's brand id on every network the brand is bound to (empty for the publisher-only path).

That local path stays free and complete; an opt-in hosted tier is live for four networks.

Managing brands

The brand-side flow adds one concept: a local brand slug. You give each client (or each of your own brands) a short nickname; the tool maps it to the network's own brand id on every network the brand is registered on. A real brands.json looks like this:

{
  "version": 1,
  "brands": {
    "acme": [
      { "network": "impact-advertiser", "credentialId": "default", "networkBrandId": "IA-12345" },
      { "network": "cj-advertiser", "credentialId": "default", "networkBrandId": "7654321" }
    ]
  }
}

The same logical brand can appear under multiple networks; that's how "earnings for Acme across all networks" fans out across the right brand id on each one. You can hand-edit this file to rename, remove, or add brands, or re-run npx affiliate-networks-mcp setup to register new ones interactively (the wizard skips brands already in the file).

Three skills are tuned for the brand side: programme-performance-report (single-brand, per-publisher rollup), agency-portfolio-rollup (every brand × network, brand-aggregated), and programme-anomaly-watch (scheduled week-over-week anomaly scan).

Use it from the terminal

call runs the same registered operations as the MCP server, for quick checks, scripts, and CI (call --help for full usage). Some calls contact an upstream network (for example generate_tracking_link mints a link). Schema-aware key=value parsing keeps string ids, converts numbers, and takes comma-separated or JSON arrays; --args '<json>' passes a full object. Results are JSON on stdout; failures are NetworkErrorEnvelope JSON on stderr with a non-zero exit.

npx affiliate-networks-mcp call --list [--network awin]
npx affiliate-networks-mcp call --describe awin list_transactions
npx affiliate-networks-mcp call awin list_transactions from=2026-01-01 limit=50

When something goes wrong

npx affiliate-networks-mcp doctor

That runs a live diagnostic across every configured network and tells you, in English, what's broken and how to fix it. If a specific network is misbehaving, append its slug:

npx affiliate-networks-mcp doctor rakuten

Most failures are one of three things: an expired token, a network that needs your approval re-confirmed, or a credential typed with a trailing space. The JSON also reports clientStrategies health; it never deletes them.

Per-network setup notes

Each network has a short page covering dashboard navigation, where to click for credentials, and common stumbling blocks:

Publisher side:

• Awin — API token + publisher ID.
• CJ Affiliate — Developer Key (GraphQL).
• eBay Partner Network — OAuth client + secret + campaign ID; approval required.
• Everflow — API key (admin-issued); experimental, built from public docs.
• Impact — Account SID + Auth Token.
• mrge — API key + secret + site ID; experimental, built from public docs.
• Partnerize — application key + user API key; experimental, built from public docs.
• PartnerStack — Partner API key; experimental, built from public docs.
• Rakuten Advertising — OAuth client + SID; approval required.
• Skimlinks — OAuth client ID + secret + publisher ID + domain ID; experimental, built from public docs.
• Sovrn Commerce — API key + secret key; experimental, built from public docs.
• Tradedoubler — bearer token + organisation ID; experimental, built from public docs.
• Admitad — OAuth2 client ID + secret + website ID; experimental, built from public docs.
• Adservice — UID + login token (cookie session); experimental, built from public docs.
• Adtraction — API token; experimental, built from public docs.
• Afilio — affiliate token + Aff ID; experimental, built from public docs.
• Commission Factory — API key; experimental, built from public docs.
• Coupang Partners — access key + secret key (HMAC); experimental, built from public docs.
• Daisycon — OAuth2 client ID + secret + refresh token + publisher ID; experimental, built from public docs.
• Eduzz — email + public key + API key; experimental, built from public docs.
• FlexOffers — API key; experimental, built from public docs.
• Hotmart — OAuth2 client ID + secret; experimental, built from public docs.
• Indoleads — bearer token; experimental, built from public docs.
• Kwanko — API token; experimental, built from public docs.
• Lomadee — app token + source ID + publisher ID + report login; experimental, built from public docs.
• Monetizze — API key; experimental, built from public docs.
• ValueCommerce — report-API key pair; experimental, built from public docs.
• Webgains — API key + publisher ID + campaign ID; experimental, built from public docs.
• Affise — per-tenant base URL + API-Key header; tenant CPA engine; experimental, built from public docs.
• Scaleo — per-tenant base URL + API key (query param); tenant engine; experimental, built from public docs.
• Offer18 — per-tenant base URL + key/aid/mid (query params); tenant engine; experimental, built from public docs.
• CAKE — per-instance base URL + API key + affiliate ID (XML API); experimental, built from public docs.
• NetRefer — per-operator base URL + OAuth2 (Azure AD); iGaming ASR reporting; experimental, built from public docs.
• Affilae — Bearer token; single-brand; FR network; experimental, built from public docs.
• Optimise Media — apikey header (Service Account); UK/IN/APAC; experimental, built from public docs.
• AccessTrade — Token header + site ID; SE-Asia/Japan, per-country base URL; experimental, built from public docs.
• Travelpayouts — X-Access-Token; global travel; experimental, built from public docs.
• Flipkart Affiliate — affiliate ID + token headers; India; experimental, built from public docs.
• Adrecord — APIKEY header; Nordic; experimental, built from public docs.
• Addrevenue — Bearer token + channel ID; Nordic; experimental, built from public docs.
• ShareASale — affiliate ID + token + secret (signed); US; experimental, built from public docs.
• Pepperjam — apiKey query param; US (Ascend, distinct from Partnerize); experimental, built from public docs.
• AvantLink — affiliate ID + auth key + website ID (query params); US/outdoor; experimental, built from public docs.
• Digistore24 — X-DS-API-KEY header; DE digital products; experimental, built from public docs.
• ClickBank — DEV:CLERK key header + nickname; digital products; experimental, built from public docs.
• TUNE — NetworkId + api_key (per-tenant host); HasOffers engine; experimental, built from public docs.
• Involve Asia — key + secret (token exchange); APAC; experimental, built from public docs.
• TradeTracker — customer ID + passphrase + site ID (SOAP session); NL/EU; experimental, built from public docs.
• Amazon Creators — API key + partner tag; single programme per marketplace; experimental, built from public docs.
• Belboon — magic key + user ID (CSV export); DACH; experimental, built from public docs.
• financeAds — API key + publisher ID; DACH finance; experimental, built from public docs.
• Adcell — API key + affiliate ID; DACH; experimental, built from public docs.
• ShopMy — Brand Partner token; US creator network; experimental, built from public docs.
• Levanta — Bearer token; Amazon creator platform; experimental, built from public docs.
• Howl — NRTV-API-KEY header + publisher ID; creator link network; smart-link minting; experimental, built from public docs.
• Yieldkit — api_key + secret (query params); link monetisation; clicks supported; experimental, built from public docs.
• eHUB — apiKey query param + publisher ID; CZ/CEE; clicks supported; experimental, built from public docs.
• LinkConnector — API key (query param); US; experimental, built from public docs.
• Connexity — publisher ID + API key; US CPC-commerce (distinct from Skimlinks); experimental, built from public docs.
• Affiliate Future — API key + password (query params); UK; 1-day pull window; experimental, built from public docs.
• Effiliation — API key (query param); FR; experimental, built from public docs.
• 2Performant — email + password (session login); Romania; experimental, built from public docs.
• Profitshare — API user + key (HMAC-signed); Romania; experimental, built from public docs.

Brand / advertiser side:

• Awin (advertiser) — OAuth bearer token; multi-brand via GET /accounts; gated to Accelerate / Advanced plans; read-only.
• CJ Affiliate (advertiser) — Personal Access Token (GraphQL); multi-brand via CID list; read-only.
• Everflow (advertiser) — API key (admin-issued); multi-brand; experimental, built from public docs.
• Impact (advertiser) — Account SID + Auth Token; agency or brand-direct; read-only.
• Partnerize (advertiser) — application key + user API key; multi-brand; experimental, built from public docs.
• PartnerStack (advertiser) — public + secret key pair (Vendor API); single-brand; experimental, built from public docs.
• Tradedoubler (advertiser) — reports token + organisation ID; multi-brand; experimental, built from public docs.
• Admitad (advertiser) — OAuth2 client ID + secret + advertiser ID; multi-brand; read-only; experimental, built from public docs.
• Adtraction (advertiser) — API token; multi-brand; read-only (POST-read allowlist); experimental, built from public docs.
• Commission Factory (advertiser) — API key; read-only; experimental, built from public docs.
• Daisycon (advertiser) — OAuth2 client ID + secret + refresh token; multi-brand; read-only; experimental, built from public docs.
• Kwanko (advertiser) — API token; multi-brand; read-only; experimental, built from public docs.
• ValueCommerce (advertiser) — report-API key pair; multi-brand; read-only; experimental, built from public docs.
• Webgains (advertiser) — API key + account ID; multi-brand; read-only; experimental, built from public docs.
• Rewardful — API Secret (HTTP Basic); single-brand; Stripe-native SaaS; experimental, built from public docs.
• FirstPromoter — API key + account ID (Bearer); single-brand; SaaS-referral; experimental, built from public docs.
• Partnero — API token (Bearer); single-brand; SaaS-referral; experimental, built from public docs.
• GrowSurf — API key + campaign ID (Bearer); single-brand; referral-credit SaaS; experimental, built from public docs.
• LeadDyno — private key (query param); single-brand; SaaS-referral; experimental, built from public docs.
• Post Affiliate Pro — per-tenant base URL + API key (Bearer); single-brand; SaaS engine; experimental, built from public docs.
• Tolt — Bearer key; single-brand; SaaS-referral; experimental, built from public docs.
• Refersion — public + secret key headers; single-brand; Shopify-heavy SaaS; experimental, built from public docs.
• Tapfiliate — X-Api-Key header; single-brand; SaaS-referral; experimental, built from public docs.

For the curious (or technical)

affiliate-mcp has five practical layers. Adapters under src/networks/ handle each network's auth, API quirks, normalisation, and capability metadata. MCP tools expose typed operations such as affiliate_awin_list_transactions; six meta-tools cover listing, diagnostics, brand resolution, and advisory client strategy. Skills and workflows compose tools into affiliate jobs. MCP prompts are reusable templates and currently Awin-specific. Setup paths connect the same local server to Claude Desktop, Claude Code, Codex, Cowork, or another compatible local stdio MCP client.

Documentation truncated — see the full README on GitHub.