# Social Intel MCP

> Instagram influencer discovery for AI agents. Pay per call in USDC via
> [x402](https://x402.org) — no API keys, no subscriptions, no sign-up.

[![MIT license](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org)
[![MCP compatible](https://img.shields.io/badge/MCP-compatible-6f42c1.svg)](https://modelcontextprotocol.io)
[![x402 payments](https://img.shields.io/badge/x402-payments-f7931a.svg)](https://x402.org)
[![socialintel.dev](https://img.shields.io/badge/homepage-socialintel.dev-222.svg)](https://socialintel.dev)
[![socialintel-mcp MCP server](https://glama.ai/mcp/servers/socialintel/socialintel-mcp/badges/score.svg)](https://glama.ai/mcp/servers/socialintel/socialintel-mcp)

[**socialintel.dev**](https://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](#-quickstart--hosted-endpoint)
- [🔌 MCP clients](#-mcp-clients)
- [🛠️ Tools](#️-tools)
- [💰 Payment flow (x402)](#-payment-flow-x402)
- [🎯 Use cases](#-use-cases)
- [🎛️ Configuration](#️-configuration)
- [🧪 Free demo mode](#-free-demo-mode)
- [🌐 Multiple transports](#-multiple-transports)
- [🔒 Privacy & telemetry](#-privacy--telemetry)
- [🗺️ Related](#️-related)
- [📄 License](#-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](#-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`

```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:

```json
{
  "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:

```json
{
  "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

```bash
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:

```json
{
  "username": "yoga_with_adriene",
  "full_name": "Adriene Mishler",
  "followers": 10500000,
  "category": "Fitness",
  "bio": "Yoga teacher & filmmaker from Austin TX",
  "public_email": "contact@adriene.com",
  "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](https://x402.org): 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`](https://pypi.org/project/x402-httpx/),
   [`agentcash`](https://github.com/merit-systems/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](https://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](#-free-demo-mode).

## 🎯 Use cases

### Micro-influencer discovery for brand outreach

```python
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)

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

LA food creators with 10K+ followers.

### Keyword + demographics fusion

```python
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

```python
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](https://socialintel.dev)
- **API docs:** [socialintel.dev/docs](https://socialintel.dev/docs)
- **OpenAPI spec:** [socialintel.dev/openapi.json](https://socialintel.dev/openapi.json)
- **x402 protocol:** [x402.org](https://x402.org)
- **agentcash (x402 CLI/SDK):** [github.com/merit-systems/agentcash](https://github.com/merit-systems/agentcash)
- **Base network (USDC):** [basescan.org](https://basescan.org)
- **CDP Bazaar discovery:** [agentic.market](https://agentic.market)
- **Model Context Protocol:** [modelcontextprotocol.io](https://modelcontextprotocol.io)

## 📄 License

MIT — see [LICENSE](./LICENSE).

## 🐛 Issues

Bug reports, feature requests, agent-integration questions:
[github.com/socialintel/socialintel-mcp/issues](https://github.com/socialintel/socialintel-mcp/issues)