@attribloom/mcp

@attribloom/mcp

Model Context Protocol server for Attribloom. It lets Claude Code, Claude Desktop, Cursor, and any other MCP client read your tenant's affiliate data and get integration guidance, using a tenant API key.

Attribloom is affiliate attribution and commission tracking for iOS apps (StoreKit 2 and App Store Server Notifications v2) and Shopify stores. Two of the seven tools need no key at all, so an agent can learn how to integrate before you have an account.

Install

Claude Code

claude mcp add attribloom --env ATTRIBLOOM_API_KEY=eak_live_... -- npx -y @attribloom/mcp

Claude Desktop / any client using mcpServers JSON

{
  "mcpServers": {
    "attribloom": {
      "command": "npx",
      "args": ["-y", "@attribloom/mcp"],
      "env": {
        "ATTRIBLOOM_API_KEY": "eak_live_..."
      }
    }
  }
}

Cursor

Settings, then MCP, then Add new server:

• Name: attribloom
• Type: command
• Command: env ATTRIBLOOM_API_KEY=eak_live_... npx -y @attribloom/mcp

HTTP transport (self-hosted)

ATTRIBLOOM_API_KEY=eak_live_... npx -y @attribloom/mcp --http

Serves Streamable HTTP at http://127.0.0.1:3000/mcp. Set PORT and HOST to override.

Get a key from the Attribloom dashboard: Settings, then API keys. Keys are shown once and are scoped read-only.

Tools

Tool	Scope required	Description
get_started_guidance	none	Public onboarding steps
connect_store_guidance	none	How to connect Shopify or an iOS app
whoami	any key	Verify the key and show tenant plus scopes
list_campaigns	read:campaigns	List campaigns and commission rules
campaign_readout	read:conversions + read:commissions	Conversions and matured commission summary
list_payouts	read:payouts	List payouts
payout_eligibility	read:payouts	Per-affiliate available balance vs threshold

Money mutations (approving an affiliate, creating a campaign, approving a payout) stay in the Attribloom dashboard and are intentionally not exposed here. This server is read-only by design.

Every figure returned comes from the real ledger. There are no estimated or projected numbers.

Environment variables

Variable	Required	Default	Description
ATTRIBLOOM_API_KEY	for data tools	none	Tenant API key from Dashboard, Settings, API keys
ATTRIBLOOM_BASE_URL	no	https://api.attribloom.com	Management API base URL
PORT	no	3000	HTTP transport port
HOST	no	127.0.0.1	HTTP transport host

Without a key the server still starts and the two guidance tools work. The data tools return a clear "API key required" message rather than failing silently.

Scope table

Scope	Tools
read:campaigns	list_campaigns
read:conversions	campaign_readout
read:commissions	campaign_readout
read:payouts	list_payouts, payout_eligibility

Example session

User: connect my Attribloom account
whoami: Tenant: Acme Corp (tenant-123), scopes: read:campaigns, read:conversions, read:commissions, read:payouts

User: what campaigns do I have?
list_campaigns: Summer Launch, Web Purchase funnel

User: how is it performing?
campaign_readout: 42 conversions, $1,240 USD matured commission

User: who can be paid out?
payout_eligibility: 3 affiliates above threshold

CLI

attribloom-mcp             # stdio transport (default; what MCP clients spawn)
attribloom-mcp --http      # Streamable HTTP transport
attribloom-mcp --version
attribloom-mcp --help

Development

npm install
npm run build
npm test

Related

• AttribloomKit: the Swift package for StoreKit 2 attribution in iOS apps
• attribloom-examples: signed postback, Shopify ref preservation, and StoreKit bind examples
• Agent onboarding guide: zero-auth integration steps written for coding agents
• OpenAPI spec

License

MIT