# Social Intel MCP Server

MCP server for Instagram influencer search. Find leads by keyword, country, category, demographics, or follower count.

**Pay per request** via [x402](https://x402.org) protocol — no API keys, no subscriptions. $0.10 USDC on Base chain per search.

## Quick Start

### Add to Claude Desktop / Claude Code

```json
{
  "mcpServers": {
    "social-intel": {
      "command": "python",
      "args": ["mcp_server.py"],
      "env": {
        "SOCIAL_INTEL_API_URL": "https://api.socialintel.dev"
      }
    }
  }
}
```

### Install & Run

```bash
pip install httpx mcp[cli]
python mcp_server.py
```

## Tools

### `search_leads`

Search Instagram influencers by demographics, location, or keyword.

| Parameter | Type | Description |
|-----------|------|-------------|
| `query` | string | Text search by name or keyword |
| `country` | string | Country code (US, UK, DE, etc) |
| `category` | string | Business category (Beauty, Fitness, Tech, etc) |
| `gender` | string | `"male"` or `"female"` |
| `min_followers` | int | Minimum follower count |
| `limit` | int | Max results (1-50, default 20) |

### Example Response

```json
{
  "results": [
    {
      "username": "fitnessguru",
      "followers": 150000,
      "category": "Fitness",
      "country": "US"
    }
  ],
  "count": 1
}
```

## Payment

This MCP server connects to the [Social Intel API](https://api.socialintel.dev) which uses the **x402 payment protocol**:

1. Your request hits the API
2. API returns `402 Payment Required` with payment instructions
3. Your x402-enabled client pays $0.10 USDC on Base automatically
4. Data is returned

For automated payment, use an [x402 Python client](https://pypi.org/project/x402/) with your wallet private key.

## API Documentation

- **API**: https://api.socialintel.dev
- **OpenAPI Spec**: https://api.socialintel.dev/openapi.json
- **Interactive Docs**: https://api.socialintel.dev/docs
- **LLM Guide**: https://api.socialintel.dev/llms.txt

## License

MIT