Content
# 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.
[](./LICENSE)
[](https://www.python.org)
[](https://modelcontextprotocol.io)
[](https://x402.org)
[](https://socialintel.dev)
[](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)
