socialintel/socialintel-mcp

Instagram influencer discovery for AI agents. Pay per call in USDC via x402 — no API keys, no subscriptions, no sign-up.

MIT license Python 3.10+ MCP compatible x402 payments socialintel.dev socialintel-mcp MCP server

socialintel.dev is a data layer for AI agents running influencer-outreach, brand-research, and creator-intelligence workflows. This repository ships an MCP server that exposes the same data through the Model Context Protocol so any MCP-compatible client (Claude, Cursor, VS Code, Cline, …) can call it natively.

📋 Table of Contents

• 🚀 Quickstart — hosted endpoint
• 🔌 MCP clients
• 🛠️ Tools
• 💰 Payment flow (x402)
• 🎯 Use cases
• 🎛️ Configuration
• 🧪 Free demo mode
• 🌐 Multiple transports
• 🔒 Privacy & telemetry
• 🗺️ Related
• 📄 License

🚀 Quickstart — hosted endpoint

Recommended. Point any MCP client that speaks HTTP/SSE or streamable transport directly at our hosted server:

https://socialintel.dev/mcp

No install, no pip, no Docker. Your agent's x402 client handles payment on each tools/call.

If your client needs a stdio wrapper (Claude Desktop on older versions, some CLI clients), see the MCP clients section for uvx / pip install setups that proxy stdio → HTTPS.

🔌 MCP clients

Claude Desktop

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

{
  "mcpServers": {
    "socialintel": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/socialintel/socialintel-mcp",
        "socialintel-mcp"
      ],
      "env": {
        "SOCIAL_INTEL_API_URL": "https://socialintel.dev"
      }
    }
  }
}

Restart Claude Desktop. search_leads appears in the tool list.

Cursor

Preferences → MCP → add server:

{
  "socialintel": {
    "command": "uvx",
    "args": ["--from", "git+https://github.com/socialintel/socialintel-mcp", "socialintel-mcp"]
  }
}

VS Code (with GitHub Copilot or Continue)

.vscode/mcp.json in your workspace:

{
  "servers": {
    "socialintel": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/socialintel/socialintel-mcp", "socialintel-mcp"]
    }
  }
}

Cline (VS Code extension)

Cline auto-detects MCP servers from cline_mcp_settings.json. Add the same server block as Claude Desktop above.

Cherry Studio / Zed / any MCP-compatible client

Use the stdio command:

uvx --from git+https://github.com/socialintel/socialintel-mcp socialintel-mcp

Or point the client at the hosted HTTP endpoint if it supports remote MCPs: https://socialintel.dev/mcp

Direct pip install

pip install git+https://github.com/socialintel/socialintel-mcp
SOCIAL_INTEL_API_URL=https://socialintel.dev socialintel-mcp

🛠️ Tools

search_leads

Search Instagram influencers by demographics, location, keyword, or business category.

Param	Type	What it does
query	string	Keyword on name/bio (e.g. yoga, travel blogger)
country	string	ISO code (US, DE, UK, IN, BR) or full name
city	string	City filter (e.g. Los Angeles). Pair with country
category	string	Fitness · Beauty · Travel · Food & Beverage · Gaming · Fashion · Lifestyle · Sports · Education · Finance · Tech · …
gender	string	male / female (also man / woman)
min_followers	int	Floor. 10000 = micro, 100000 = macro
max_followers	int	Ceiling. 100000 excludes mega-accounts
limit	int	1–100 (default 20). Price scales with limit
demo	bool	true = 3 free preview results, no payment

Each result:

{
  "username": "yoga_with_adriene",
  "full_name": "Adriene Mishler",
  "followers": 10500000,
  "category": "Fitness",
  "bio": "Yoga teacher & filmmaker from Austin TX",
  "public_email": "[email protected]",
  "is_verified": true,
  "is_business": true,
  "gender": "woman"
}

public_email is populated where available — higher on business-verified accounts, lower on personal creator accounts (Instagram platform reality, not a filter we apply).

💰 Payment flow (x402)

Agent payments follow the x402 protocol: a 402 Payment Required response carries signed payment requirements; the client signs a USDC transfer and retries; the server verifies + settles through a facilitator and returns results.

1. Agent calls search_leads(category="Fitness", country="US").
2. Server replies HTTP 402 with extensions.bazaar metadata and accepts blocks for Base (USDC) and Solana (USDC).
3. If the client runs an x402 client library (x402-httpx, agentcash, the TypeScript x402 package, etc.), it signs a transfer on either chain and retries.
4. Our server verifies + settles via the CDP facilitator (primary — also catalogues us on agentic.market) or PayAI facilitator (fallback). Results return on the retried call.

Pricing — transparent per-call, no minimums:

Limit	USDC
1–20	$0.50
50	$0.80
100	$1.30

Formula: $0.50 + max(0, limit − 20) × $0.01.

Free demo with demo=true skips payment entirely; see Free demo mode.

🎯 Use cases

Micro-influencer discovery for brand outreach

search_leads(
    category="Beauty",
    country="US",
    min_followers=15000,
    max_followers=200000,
    limit=50,
)

Returns 50 beauty micro-influencers in the US, with public business emails where available.

Local creator sourcing (city-level)

search_leads(
    city="Los Angeles",
    category="Food & Beverage",
    min_followers=10000,
    limit=20,
)

LA food creators with 10K+ followers.

Keyword + demographics fusion

search_leads(
    query="personal trainer",
    gender="female",
    country="United Kingdom",
    min_followers=50000,
    max_followers=500000,
)

Female personal trainers in the UK, mid-to-large follower tier.

Free exploration before paying

search_leads(category="Travel", country="Germany", demo=True)

Returns 3 preview results with no payment — perfect for validating filters before spending.

🎛️ Configuration

Env var	Default	Purpose
SOCIAL_INTEL_API_URL	http://localhost:8000	Base URL for the upstream API. Set to https://socialintel.dev for production.
POSTHOG_API_KEY	(empty)	Optional — if set, the MCP server emits anonymous usage events to PostHog. Empty by default so there's no silent telemetry.
POSTHOG_HOST	https://us.i.posthog.com	Only used when POSTHOG_API_KEY is set.

🧪 Free demo mode

Pass demo=true on any search_leads call. You get up to 3 preview results, no payment required. The response includes an upgrade_message pointing at the paid URL so your agent can switch to paid mode after validating filters.

Demo is rate-limited to 5 requests per IP per hour. It reads from our cache rather than the live data source, so content reflects recent queries rather than live platform state.

🌐 Multiple transports

• stdio (default) — uvx --from git+... socialintel-mcp
• HTTPS / streamable — connect directly to https://socialintel.dev/mcp
• SSE — the hosted endpoint also serves Server-Sent Events for clients that prefer it

The hosted endpoint is the simplest path — zero install, identical tool definitions.

🔒 Privacy & telemetry

This server emits one anonymous event per tool call when POSTHOG_API_KEY is set:

• mcp_search_leads — includes only the filter shape (query, country, category, gender, follower range, limit, demo flag) and the resulting row count. No profile usernames, no emails, no payer addresses.

Events are off by default (no key means no capture). If you enable telemetry you can point it at your own PostHog project — set POSTHOG_API_KEY to your own key and the events go to your instance, not ours.

Payment-level telemetry (x402 settle, transaction hashes, revenue) is captured server-side by socialintel.dev, not by this MCP wrapper.

🗺️ Related

• Website: socialintel.dev
• API docs: socialintel.dev/docs
• OpenAPI spec: socialintel.dev/openapi.json
• x402 protocol: x402.org
• agentcash (x402 CLI/SDK): github.com/merit-systems/agentcash
• Base network (USDC): basescan.org
• CDP Bazaar discovery: agentic.market
• Model Context Protocol: modelcontextprotocol.io

📄 License

MIT — see LICENSE.

🐛 Issues

Bug reports, feature requests, agent-integration questions: github.com/socialintel/socialintel-mcp/issues