impactdotcom-mcp

A local MCP server that wraps the Impact.com partner REST API so you can query and act on your affiliate/partnership data from Claude Code, Claude Desktop, or any MCP client.

Its primary focus is diagnosing publisher tracking problems — most importantly "I'm getting clicks but no revenue" — by exposing the full click → action → revenue funnel, tracing individual orders, and filing dispute (action inquiry) tickets when conversions don't track.

Why a custom server? Impact.com ships a hosted MCP at https://mcp.impact.com/mcp, but it can't be connected from Claude Code: its OAuth server doesn't support Dynamic Client Registration (RFC 7591) and the static client id is unpublished. This server talks to Impact's REST API directly with an API key, sidestepping the OAuth blocker entirely.

What it can do

• Diagnose tracking — one call (diagnose_tracking) pulls clicks, actions (across PENDING/APPROVED/REVERSED), and revenue for a window and explains, in plain English, why you're seeing clicks but no revenue.
• Trace a specific order — find an action by OrderId, see its state and reversal reason, or confirm a click recorded.
• Run reports — list/run any report your token can access (Performance by Brand, Action Listing, etc.).
• File disputes — open UNTRACKED/INCORRECT/DECLINED action inquiries for orders that didn't track (gated behind a write flag).
• Generate tracking links and reach any endpoint via fenced escape-hatch tools.

Example: "clicks but no revenue"

Ask Claude "why am I getting clicks but no revenue this month?" and diagnose_tracking returns something like:

{
  "diagnosis": {
    "summary": "Clicks are landing but there are NO actions in any state. Your conversions are not reaching Impact.",
    "counts": { "clicks": 10, "actionsTotal": 0, "pending": 0, "approved": 0, "reversed": 0 },
    "likelyCauses": [
      "The conversion tag/postback isn't firing, or fires without the click id (irclickid) — so Impact can't attribute it.",
      "Mobile clicks that complete the purchase in the retailer's app or a new browser session lose the irclickid.",
      "Reporting delay: actions can take up to 48 hours to appear."
    ],
    "nextChecks": [
      "Run export_clicks for the click day(s) to inspect each click's DeviceType and irclickid.",
      "Click the tracking link → complete checkout in the SAME session, and confirm the order carries that irclickid.",
      "Take a recorded irclickid to support (or file an ActionInquiry) and ask why no action was created."
    ]
  }
}

From there you can export_clicks to see device/irclickid detail, find_action_by_order to trace a test order, and — if conversions genuinely didn't track — create_action_inquiry to file the dispute.

Requirements

• Node ≥ 20 (uses native fetch).
• An Impact.com account and API credentials (Settings → API → Account SID + Auth Token). A scoped token is recommended; grant the APIs you need (Actions, Reports, Clicks/ClickExport, ActionInquiries, etc.).

Quick start

git clone https://github.com/gblush/impactdotcom-mcp.git
cd impactdotcom-mcp
npm install
cp .env.example .env      # then fill in your real credentials (see below)
npm run build
npm run inspect           # optional: open the MCP Inspector to try the tools

Configuration

Set these in .env (gitignored) or your environment:

Variable	Required	Default	Description
IMPACT_ACCOUNT_SID	yes	—	Basic-auth username (your Account SID, starts with IR)
IMPACT_AUTH_TOKEN	yes	—	Basic-auth password (secret)
IMPACT_ACCOUNT_TYPE	no	Mediapartners	API persona: Mediapartners (publisher) or Advertisers (brand)
IMPACT_BASE_URL	no	https://api.impact.com	API base URL override
IMPACT_ENABLE_WRITES	no	false	set true to register the write tools
IMPACT_MAX_CONCURRENCY	no	4	max concurrent API requests (rate-limit guardrail, 1–16)

Register with Claude Code

A project-scoped .mcp.json is included. With .env in place and npm run build done, open the project in Claude Code and approve the server. Or register it explicitly (use --scope user to make it available everywhere):

claude mcp add impactdotcom --scope local -- node /absolute/path/to/impactdotcom-mcp/dist/index.js

Tools

Diagnostics (the point of this server)

• diagnose_tracking — pull the clicks → actions → revenue funnel for a window and explain why you may see clicks but no revenue.
• list_actions — conversions/commissions; scans PENDING + APPROVED + REVERSED by default so test/reversed orders surface.
• get_action — full detail for one action.
• find_action_by_order — trace an order by OrderId (incl. reversal reason) via the Advanced Action Listing report.
• get_click / export_clicks — confirm a click recorded / list a day's clicks (device, irclickid, landing page).
• list_action_inquiries / get_action_inquiry — view dispute tickets you've filed.

Reporting & catalog

• list_reports, get_report_metadata, run_report, run_report_export
• list_campaigns, get_campaign, list_catalogs, list_catalog_items, get_account
• impact_api_get — read-only escape hatch: GET any persona-scoped endpoint.

Writes (only when IMPACT_ENABLE_WRITES=true)

• create_action_inquiry — file an UNTRACKED/INCORRECT/DECLINED dispute for an order.
• create_tracking_link — generate a tracking/deep link for a program.
• impact_api_request — write escape hatch (POST/PUT/DELETE).

How it works

• src/client.ts is the only module that talks HTTP — auth, JSON negotiation, pagination (@nextpageuri), retries, and async jobs (ClickExport/ReportExport) all live here.
• src/diagnostics.ts encodes Impact's attribution rules and reversal codes so diagnose_tracking can interpret the funnel.
• src/tools/* is one file per domain; writes are gated in src/tools/index.ts.

A few Impact.com quirks the server handles for you (verified against the live API):

• Paths are persona-prefixed: /{IMPACT_ACCOUNT_TYPE}/{AccountSID}/…. If every call 403s, the account type is likely wrong (Mediapartners vs Advertisers).
• The API defaults to XML; the client always sends Accept: application/json.
• Date formats differ by endpoint: tool inputs are YYYY-MM-DD, but /Actions and /ActionInquiries need full ISO-8601 datetimes (the server converts them), while report filters take bare dates.
• Report ids and filter names vary per report — call get_report_metadata first.
• Rate limits: the API enforces an hourly quota (and exports like ClickExport are expensive). The client caps concurrent requests (IMPACT_MAX_CONCURRENCY), and on a 429 it retries only if the reset is within 30s — otherwise it fails fast with the reset time rather than blocking the call for hours.

Security

Real credentials live only in the gitignored .env. No secrets or PII belong in any tracked file (.env.example, .mcp.json, and docs use placeholders). Run npm run check:secrets before committing — it scans the tree against your real .env values and fails if anything leaks.

Development

npm run dev          # watch-mode run via tsx
npm run typecheck    # tsc --noEmit
npm run lint         # eslint (enforces no stray console.log; stdout is JSON-RPC only)
npm run check:secrets

License

MIT © 2026 Eric Blush