affiliatemcp

# affiliate-mcp

> Integrate your affiliate networks with Claude or Codex.

[![npm version](https://img.shields.io/npm/v/affiliate-networks-mcp?label=release)](https://www.npmjs.com/package/affiliate-networks-mcp) ![networks](https://img.shields.io/badge/networks-72-blue) ![adapters](https://img.shields.io/badge/adapters-86-blue) [![maintained by](https://img.shields.io/badge/maintained%20by-community%20%2F%20networks-orange)](./docs/networks)

> **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`](https://github.com/bobberrisford/affiliatemcp/issues?q=is%3Aissue+is%3Aopen+label%3Aadopt-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](./docs/product/manifesto.md).

## 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`](./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`](./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](https://github.com/bobberrisford/affiliatemcp/releases/latest).
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](./docs/updating.md)).
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`](./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](https://nodejs.org/).

**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](#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.

<details>
<summary>Prefer to edit Claude Desktop config by hand?</summary>

Open the Claude Desktop config file at:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windo