内容
# 社交智能 MCP
> 为 AI 代理提供 Instagram 网红发现功能。通过 [x402](https://x402.org) 以 USDC 支付 — 无需 API 密钥，无需订阅，无需注册。
[](./LICENSE)
[](https://www.python.org)
[](https://modelcontextprotocol.io)
[](https://x402.org)
[](https://socialintel.dev)
[](https://glama.ai/mcp/servers/socialintel/socialintel-mcp)
[**社交智能官网**](https://socialintel.dev) 是一个为 AI 代理提供数据层的平台，适用于网红外联、品牌研究和创作者情报工作流程。本仓库提供一个 MCP 服务器，通过模型上下文协议公开相同的数据，因此任何 MCP 兼容的客户端（Claude、Cursor、VS Code、Cline 等）都可以原生调用它。
## 📋 目录
- [🚀 快速开始 — 主机端点](#-快速开始--主机端点)
- [🔌 MCP 客户端](#-mcp-客户端)
- [🛠️ 工具](#️-工具)
- [💰 支付流程（x402）](#-支付流程-x402)
- [🎯 用例](#-用例)
- [🎛️ 配置](#️-配置)
- [🧪 免费演示模式](#-免费演示模式)
- [🌐 多种传输方式](#-多种传输方式)
- [🔒 隐私和遥测](#-隐私和遥测)
- [🗺️ 相关](#️-相关)
- [📄 许可证](#-许可证)
## 🚀 快速开始 — 主机端点
**推荐。** 将任何支持 HTTP/SSE 或可流式传输的 MCP 客户端直接指向我们的主机服务器：
```
https://socialintel.dev/mcp
```
无需安装，无需 pip，无需 Docker。您的代理的 x402 客户端在每次 `tools/call` 时处理支付。
如果您的客户端需要 stdio 包装器（旧版 Claude Desktop，一些 CLI 客户端），请参阅 [MCP 客户端](#-mcp-客户端) 部分，了解 `uvx` / `pip install` 设置，这些设置代理 stdio → HTTPS。
## 🔌 MCP 客户端
### 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"
}
}
}
}
```
重启 Claude Desktop。`search_leads` 出现在工具列表中。
### Cursor
首选项 → MCP → 添加服务器：
```json
{
"socialintel": {
"command": "uvx",
"args": ["--from", "git+https://github.com/socialintel/socialintel-mcp", "socialintel-mcp"]
}
}
```
### VS Code（带有 GitHub Copilot 或 Continue）
工作区中的 `.vscode/mcp.json`：
```json
{
"servers": {
"socialintel": {
"command": "uvx",
"args": ["--from", "git+https://github.com/socialintel/socialintel-mcp", "socialintel-mcp"]
}
}
}
```
### Cline（VS Code 扩展）
Cline 从 `cline_mcp_settings.json` 自动检测 MCP 服务器。添加与上面 Claude Desktop 相同的服务器块。
### Cherry Studio / Zed / 任何 MCP 兼容客户端
使用 stdio 命令：
```
uvx --from git+https://github.com/socialintel/socialintel-mcp socialintel-mcp
```
或将客户端指向托管的 HTTP 端点（如果支持远程 MCP）：`https://socialintel.dev/mcp`
### 直接 pip 安装
```bash
pip install git+https://github.com/socialintel/socialintel-mcp
SOCIAL_INTEL_API_URL=https://socialintel.dev socialintel-mcp
```
## 🛠️ 工具
### `search_leads`
按人口统计、位置、关键词或商业类别搜索 Instagram 网红。
| 参数 | 类型 | 功能 |
|---|---|---|
| `query` | 字符串 | 名称/简介中的关键词（例如 `yoga`、`travel blogger`） |
| `country` | 字符串 | ISO 代码（`US`、`DE`、`UK`、`IN`、`BR`）或全名 |
| `city` | 字符串 | 城市过滤器（例如 `Los Angeles`）。与 `country` 配对 |
| `category` | 字符串 | `健身` · `美容` · `旅行` · `食品饮料` · `游戏` · `时尚` · `生活方式` · `体育` · `教育` · `金融` · `科技` · … |
| `gender` | 字符串 | `male` / `female`（也支持 `man` / `woman`） |
| `min_followers` | 整数 | 底线。`10000` = 微型，`100000` = 大型 |
| `max_followers` | 整数 | 上限。`100000` 排除超级账户 |
| `limit` | 整数 | 1–100（默认 20）。价格随限制缩放 |
| `demo` | 布尔值 | `true` = 3 个免费预览结果，无需支付 |
每个结果：
```json
{
"username": "yoga_with_adriene",
"full_name": "Adriene Mishler",
"followers": 10500000,
"category": "健身",
"bio": "来自奥斯汀 TX 的瑜伽老师和电影制片人",
"public_email": "contact@adriene.com",
"is_verified": true,
"is_business": true,
"gender": "woman"
}
```
`public_email` 在可用时填充 — 在商业验证账户上更高，在个人创作者账户上更低（Instagram 平台现实，而不是我们应用的过滤器）。
## 💰 支付流程（x402）
代理支付遵循 [x402 协议](https://x402.org)：需要 402 支付的响应带有签名的支付要求；客户端签名一个 USDC 转账并重试；服务器验证 + 通过促进者结算并返回结果。
1. 代理调用 `search_leads(category="Fitness", country="US")`。
2. 服务器回复 `HTTP 402`，带有 `extensions.bazaar` 元数据，并接受 **Base（USDC）** 和 **Solana（USDC）** 的区块。
3. 如果客户端运行 x402 客户端库（[`x402-httpx`](https://pypi.org/project/x402-httpx/)、[`agentcash`](https://github.com/merit-systems/agentcash)、TypeScript `x402` 包等），它在任一链上签名一个转账并重试。
4. 我们的服务器通过 **CDP 促进者**（主要 — 也在 [agentic.market](https://agentic.market) 上注册我们）或 **PayAI 促进者**（备用）验证 + 结算。结果在重试调用时返回。
**定价** — 透明的每次调用，无最低消费：
| 限制 | USDC |
|---|---|
| 1–20 | $0.50 |
| 50 | $0.80 |
| 100 | $1.30 |
公式：`$0.50 + max(0, limit − 20) × $0.01`。
免费演示模式下，`demo=true` 完全跳过支付；参见 [免费演示模式](#-免费演示模式)。
## 🎯 用例
### 品牌外联的微型网红发现
```python
search_leads(
category="美容",
country="US",
min_followers=15000,
max_followers=200000,
limit=50,
)
```
返回 50 个美国的美容微型网红，提供公共商业电子邮件。
### 本地创作者采购（城市级别）
```python
search_leads(
city="洛杉矶",
category="食品饮料",
min_followers=10000,
limit=20,
)
```
洛杉矶 10K+ 粉丝的食品创作者。
### 关键词 + 人口统计融合
```python
search_leads(
query="私人教练",
gender="女性",
country="英国",
min_followers=50000,
max_followers=500000,
)
```
英国中大型粉丝群的女性私人教练。
### 付费前免费探索
```python
search_leads(category="旅行", country="德国", demo=True)
```
返回 3 个预览结果，无需支付 — 非常适合在消费前验证过滤器。
## 🎛️ 配置
| 环境变量 | 默认值 | 目的 |
|---|---|---|
| `SOCIAL_INTEL_API_URL` | `http://localhost:8000` | 上游 API 的基本 URL。设置为 `https://socialintel.dev` 以进行生产。 |
| `POSTHOG_API_KEY` | （空） | 可选 — 如果设置，MCP 服务器会发出匿名使用事件到 PostHog。默认为空，因此没有静默遥测。 |
| `POSTHOG_HOST` | `https://us.i.posthog.com` | 仅在设置 `POSTHOG_API_KEY` 时使用。 |
## 🧪 免费演示模式
在任何 `search_leads` 调用中传递 `demo=true`。您最多可以获得 3 个预览结果，无需支付。响应中包含一个 `upgrade_message`，指向付费 URL，以便您的代理在验证过滤器后切换到付费模式。
演示模式的速率限制为每个 IP 每小时 5 次请求。它从我们的缓存中读取，而不是实时数据源，因此内容反映最近的查询而不是实时平台状态。
## 🌐 多种传输方式
- **stdio** （默认）— `uvx --from git+... socialintel-mcp`
- **HTTPS / 可流式传输** — 直接连接到 `https://socialintel.dev/mcp`
- **SSE** — 主机端点还为优先使用它的客户端提供服务器发送事件
主机端点是最简单的路径 — 零安装，相同的工具定义。
## 🔒 隐私和遥测
当设置 `POSTHOG_API_KEY` 时，该服务器在每次工具调用时发出一个匿名事件：
- `mcp_search_leads` — 仅包括过滤器形状（查询、国家、类别、性别、关注者范围、限制、演示标志）和结果行数。没有配置文件用户名、没有电子邮件、没有付款地址。
事件**默认关闭**（无密钥意味着无捕获）。如果您启用遥测，您可以将它指向自己的 PostHog 项目 — 设置 `POSTHOG_API_KEY` 为您自己的密钥，事件将发送到您的实例，而不是我们的。
支付级别的遥测（x402 结算、交易哈希、收入）由 socialintel.dev 服务器端捕获，而不是由这个 MCP 包装器捕获。
## 🗺️ 相关
- **官网：** [socialintel.dev](https://socialintel.dev)
- **API 文档：** [socialintel.dev/docs](https://socialintel.dev/docs)
- **OpenAPI 规范：** [socialintel.dev/openapi.json](https://socialintel.dev/openapi.json)
- **x402 协议：** [x402.org](https://x402.org)
- **agentcash（x402 CLI/SDK）：** [github.com/merit-systems/agentcash](https://github.com/merit-systems/agentcash)
- **Base 网络（USDC）：** [basescan.org](https://basescan.org)
- **CDP Bazaar 发现：** [agentic.market](https://agentic.market)
- **模型上下文协议：** [modelcontextprotocol.io](https://modelcontextprotocol.io)
## 📄 许可证
MIT — 参见 [LICENSE](./LICENSE)。
## 🐛 问题
错误报告、功能请求、代理集成问题：[github.com/socialintel/socialintel-mcp/issues](https://github.com/socialintel/socialintel-mcp/issues)
