Social Perks

Official10 toolsLive

by benzatkulak-collab · TypeScript

Agent-native marketing platform: create campaigns, submit proofs, review submissions.

The io.github.benzatkulak-collab/socialperks MCP server provides an agent-native marketing platform. It supports creating campaigns, submitting proofs, and reviewing submissions. The server includes 10 tools and is positioned as a campaign execution layer with infrastructure for marketing actions across multiple platforms.

🛠️ Key Features

Create campaigns
Submit proofs
Review submissions
Marketing infrastructure for campaigns and execution
10 tools

🚀 Use Cases

Running marketing campaigns end-to-end
Collecting and validating “proof” submissions
Reviewing submissions for campaigns

⚡ Developer Benefits

Local development via npm install and npm run dev
Demo accounts with PIN 1234

⚠️ Limitations

The provided data does not specify the exact tool names, interfaces, or schema details beyond the supported actions.

Captured live from the server via tools/list.

getPricing

Get the market-rate pricing for a marketing action. Returns USD value and recommended perk type/value.

Parameters3

actionId	string	optional	Action ID (e.g. ig_post, google_review)
platformId	string	optional	Platform ID (e.g. instagram, google)
businessType	string	optional	Business type modifier (default: general)

Raw schema

{
  "type": "object",
  "properties": {
    "actionId": {
      "type": "string",
      "description": "Action ID (e.g. ig_post, google_review)"
    },
    "platformId": {
      "type": "string",
      "description": "Platform ID (e.g. instagram, google)"
    },
    "businessType": {
      "type": "string",
      "description": "Business type modifier (default: general)"
    }
  }
}

listActions

List the 107 marketing actions available on Social Perks. Filterable by platform, type, and effort.

Parameters5

platformId	string	optional
type	string	optional
maxEffort	integer	optional
page	integer	optional
perPage	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "platformId": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "enum": [
        "content",
        "review",
        "engage",
        "share",
        "referral"
      ]
    },
    "maxEffort": {
      "type": "integer",
      "minimum": 0,
      "maximum": 5
    },
    "page": {
      "type": "integer",
      "default": 1
    },
    "perPage": {
      "type": "integer",
      "default": 50
    }
  }
}

getBenchmarks

Get industry benchmarks (engagement rate, conversion rate, etc.).

Parameters1

industry

string

optional

Raw schema

{
  "type": "object",
  "properties": {
    "industry": {
      "type": "string"
    }
  }
}

listCampaigns

List campaigns. Requires auth — returns the caller's campaigns.

Parameters1

status

string

optional

Raw schema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "draft",
        "active",
        "paused",
        "completed"
      ]
    }
  }
}

searchInfluencers

Search influencers by platform and follower count.

Parameters2

platform	string	optional
minFollowers	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "platform": {
      "type": "string"
    },
    "minFollowers": {
      "type": "integer"
    }
  }
}

createCampaign

Create and launch a new campaign for the calling business. Returns the campaign id, name, and dashboard URL. The campaign goes live immediately — no separate publish step.

Parameters8

businessId	string	required	The business owning this campaign. Must match the API key's business.
name	string	required	Customer-facing campaign name
description	string	optional	Optional internal description
actions	array	required	Action IDs the campaign accepts (e.g. ['ig_st'] for an Instagram Story Tag).
discountValue	number	required	Discount amount. Capped at 100 for pct, 10000 for dol.
discountType	string	required	Discount denomination: 'pct' for percentage, 'dol' for dollars off.
maxCompletions	integer \| null	optional	Optional cap on total completions. Null = no cap.
expiresInDays	integer	optional	Days until the campaign auto-expires. Default 60.

Raw schema

{
  "type": "object",
  "properties": {
    "businessId": {
      "type": "string",
      "description": "The business owning this campaign. Must match the API key's business."
    },
    "name": {
      "type": "string",
      "description": "Customer-facing campaign name",
      "maxLength": 200
    },
    "description": {
      "type": "string",
      "description": "Optional internal description"
    },
    "actions": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "description": "Action IDs the campaign accepts (e.g. ['ig_st'] for an Instagram Story Tag)."
    },
    "discountValue": {
      "type": "number",
      "minimum": 0.01,
      "description": "Discount amount. Capped at 100 for pct, 10000 for dol."
    },
    "discountType": {
      "type": "string",
      "enum": [
        "pct",
        "dol"
      ],
      "description": "Discount denomination: 'pct' for percentage, 'dol' for dollars off."
    },
    "maxCompletions": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Optional cap on total completions. Null = no cap."
    },
    "expiresInDays": {
      "type": "integer",
      "minimum": 1,
      "maximum": 365,
      "description": "Days until the campaign auto-expires. Default 60."
    }
  },
  "required": [
    "businessId",
    "name",
    "actions",
    "discountValue",
    "discountType"
  ]
}

submitProof

Submit proof of completion for a campaign action — a public URL to a post, a screenshot, a video, or platform-verified data. The submission enters a review queue (or auto-approves depending on the campaign's verification mode).

Parameters5

campaignId	string	required	Campaign the submission applies to.
actionId	string	required	Specific action being completed (must be allowed by the campaign).
proofUrl	string	required	Public URL of the proof. For url-type submissions, the platform verifier will fetch this.
proofType	string	required	How the proof was captured. 'url' triggers automated verification.
metadata	object	optional	Optional bag of context (poster handle, post timestamp, etc.).

Raw schema

{
  "type": "object",
  "properties": {
    "campaignId": {
      "type": "string",
      "description": "Campaign the submission applies to."
    },
    "actionId": {
      "type": "string",
      "description": "Specific action being completed (must be allowed by the campaign)."
    },
    "proofUrl": {
      "type": "string",
      "description": "Public URL of the proof. For url-type submissions, the platform verifier will fetch this.",
      "maxLength": 2048
    },
    "proofType": {
      "type": "string",
      "enum": [
        "screenshot",
        "url",
        "video",
        "api_verified"
      ],
      "description": "How the proof was captured. 'url' triggers automated verification."
    },
    "metadata": {
      "type": "object",
      "description": "Optional bag of context (poster handle, post timestamp, etc.).",
      "additionalProperties": true
    }
  },
  "required": [
    "campaignId",
    "actionId",
    "proofUrl",
    "proofType"
  ]
}

reviewSubmission

Approve or reject a submission. Approving releases the perk; rejecting requires a reason. Use this when the business chooses manual review over auto-verification.

Parameters3

submissionId	string	required	Submission id from a prior submitProof call.
decision	string	required	Approve releases the perk. Reject explains why the proof was insufficient.
reason	string	optional	Required when decision='reject'. 1-500 chars.

Raw schema

{
  "type": "object",
  "properties": {
    "submissionId": {
      "type": "string",
      "description": "Submission id from a prior submitProof call."
    },
    "decision": {
      "type": "string",
      "enum": [
        "approve",
        "reject"
      ],
      "description": "Approve releases the perk. Reject explains why the proof was insufficient."
    },
    "reason": {
      "type": "string",
      "description": "Required when decision='reject'. 1-500 chars.",
      "maxLength": 500
    }
  },
  "required": [
    "submissionId",
    "decision"
  ]
}

listSubmissions

List submissions for a business or campaign, filterable by state (pending/approved/rejected). Returns paginated results.

Parameters5

businessId	string	optional
campaignId	string	optional
state	string	optional
page	integer	optional
perPage	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "businessId": {
      "type": "string"
    },
    "campaignId": {
      "type": "string"
    },
    "state": {
      "type": "string",
      "enum": [
        "pending",
        "approved",
        "rejected"
      ]
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "default": 1
    },
    "perPage": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    }
  }
}

getCampaignStats

Get summary stats for a single campaign — total submissions, approved count, conversion rate, perks issued, and time-to-first-submission. Useful for an agent reporting back to its user.

Parameters1

campaignId

string

required

Campaign to fetch stats for.

Raw schema

{
  "type": "object",
  "properties": {
    "campaignId": {
      "type": "string",
      "description": "Campaign to fetch stats for."
    }
  },
  "required": [
    "campaignId"
  ]
}

README.md1 KBView on GitHub

The Marketing Value Protocol — AI-powered marketing infrastructure for every business.

107 marketing actions across 15 platforms. Pricing oracle for AI agents. Campaign execution layer.

Quick Start

bash

npm install
npm run dev

Open http://localhost:3000.

Demo Accounts

All use PIN: 1234

Email	Business Type
yoga@demo.com	Yoga Studio
sol@demo.com	Restaurant
glow@demo.com	Salon
iron@demo.com	Gym
baked@demo.com	Coffee Shop
ink@demo.com	Tattoo Parlor
vet@demo.com	Veterinarian
bloom@demo.com	Florist
smith@demo.com	Law Firm
spark@demo.com	Auto Mechanic

Or sign up as any business type — the AI adapts.

Tech Stack

Next.js 15 (App Router)
React 19
TypeScript
Tailwind CSS
Instrument Serif + DM Sans + JetBrains Mono

Using with Claude Code

This project includes a CLAUDE.md file that gives Claude Code full context about the architecture, design system, and what needs building next. Just run:

bash

claude

in the project directory and Claude will understand the full codebase.

License

Install

Tools (10)

getPricinglistActionsgetBenchmarkslistCampaignssearchInfluencerscreateCampaignsubmitProofreviewSubmission

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://socialperks.app/api/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "socialperks": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://socialperks.app/api/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

getPricing

listActions

getBenchmarks

listCampaigns

searchInfluencers

createCampaign

submitProof

reviewSubmission

listSubmissions

getCampaignStats

Social Perks

Quick Start

Demo Accounts

Tech Stack

Using with Claude Code

License

Install

Remote endpoint

Related servers