Pearch

Pearch.ai MCP

Pearch.AI 的 MCP 服务：通过自然语言搜索人员和公司/潜在客户（B2B）。可在 Claude、Cursor、VS Code 或任何兼容 MCP 的客户端中使用。

基于人类偏好的 AI 招聘寻源工具评估

工具

工具	描述
search_people	通过自然语言 query 或结构化 search_requirements 搜索人员。支持快速/专业/超快速搜索类型、联系人信息揭示和联系人筛选条件、实时资料刷新、洞察，以及基于会话的分页和后续查询。
search_company_leads	查找公司及其潜在客户/联系人（B2B）。示例：公司 “SF 的 AI 初创公司，50–200 名员工” + 潜在客户 “CTO 和工程经理”，并可选择生成个性化的拓展消息。
get_profile	通过 LinkedIn slug 或电子邮件查找并丰富单个人员资料（联系人信息揭示、实时刷新、GitHub 信息补充）。
get_user_info	已认证用户信息：电子邮件、剩余额度、定价方案。免费。

结构化人员搜索

如果你已有一组筛选条件，可将 search_requirements 传给 search_people：

{
  "search_requirements": [
    {
      "search_requirement": "Software engineer with 5+ years of Python experience",
      "must_have": true
    },
    {
      "search_requirement": "Experience at a fintech company",
      "must_have": false
    }
  ],
  "search_type": "fast",
  "limit": 10,
  "insights": true,
  "reveal_emails": true
}

• search_requirement：必填，且不能为空。每项条件应简短、独立。
• must_have：必填条件设为 true，偏好条件（非必需）设为 false（默认值）。

列表必须至少包含一项要求。使用 search_requirements 时，query 为可选项；如果两者都提供，API 会优先采用 search_requirements。请参阅 Pearch 搜索 API 合约。

两种输入均支持相同的搜索选项：搜索类型、洞察和评分、资料刷新、联系人信息揭示和筛选条件、严格筛选、低置信度结果、时间预算、分页、响应字段、资料排除以及免费的掩码结果。两种输入的搜索类型限制相同；例如，superfast 不支持洞察、资料评分或高新鲜度。

分页时，请发送返回的 thread_id 和 limit，并可选择附带 offset，同时省略 query 和 search_requirements。如需更改条件，请在不带 thread_id 的情况下开始新搜索。现有的 query 调用和会话后续查询仍会照常转发；后续查询参数是否被接受由 API 决定。

此 MCP 服务不提供 custom_filters。请改用 query 或 search_requirements 表达条件。

远程服务（推荐）

托管服务地址为 https://mcp.pearch.ai/mcp，同时支持两种身份验证方案：

OAuth（无需处理密钥）

添加服务时无需任何标头 — 支持 OAuth 的客户端（Claude、Cursor、VS Code）会自动发现验证流程并打开 Google 登录页面。请使用电子邮件地址与 Pearch 账户匹配的 Google 账户登录：

claude mcp add --transport http pearch https://mcp.pearch.ai/mcp

搜索费用将从你自己的 Pearch 账户额度中扣除。如果你的 Pearch 账户尚无 API key，请先在 Pearch.ai 控制台中创建一个。

API key

传入与 api.pearch.ai 相同的 Pearch API key：

{
  "mcpServers": {
    "Pearch.ai": {
      "url": "https://mcp.pearch.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${env:PEARCH_API_KEY}"
      }
    }
  }
}

使用 test_mcp_key 获取掩码（示例）结果 — 无需注册。

本地（stdio）安装

需要 Python 3.10+ 和 pip install -r requirements.txt（或 pip install fastmcp）。

Claude Desktop / Claude Code

fastmcp install claude-desktop pearch_mcp.py --env PEARCH_API_KEY=test_mcp_key

或者在 mcpServers 下手动配置：

"Pearch.ai": {
  "command": "python",
  "args": ["/path/to/mcp_pearch/pearch_mcp.py"],
  "env": { "PEARCH_API_KEY": "test_mcp_key" }
}

Cursor

fastmcp install cursor pearch_mcp.py --env PEARCH_API_KEY=test_mcp_key

如需获取完整结果，请将 test_mcp_key 替换为你的控制台密钥。

运行自己的 HTTP 服务

uvicorn pearch_mcp:app --host 0.0.0.0 --port 8000

健康检查：GET /health 或 /healthcheck（报告身份验证模式）。

环境变量

变量	默认值	用途
PEARCH_MCP_AUTH	api_key	oauth | api_key | none。在 oauth 模式下，仍接受原始 API 密钥承载令牌（双重身份验证）。
PEARCH_MCP_BASE_URL	http://localhost:8000	此服务的公开 URL。OAuth 元数据、令牌受众以及 /auth/callback 重定向 URI 均由此生成。
PEARCH_MCP_GOOGLE_CLIENT_ID / PEARCH_MCP_GOOGLE_CLIENT_SECRET	—	Google OAuth 2.0 Web 应用客户端（将 <base_url>/auth/callback 注册为重定向 URI）。oauth 模式下必需。
PEARCH_MCP_INTERNAL_TOKEN	—	用于内部邮箱→API 密钥映射和请求来源签名的共享密钥。oauth 模式以及使用 API 密钥进行已验证 MCP 来源归因时必需。必须与后端的 MCP_INTERNAL_TOKEN 一致；切勿分发给最终用户。
PEARCH_MCP_OAUTH_STORE	disk	redis 会将 OAuth 状态（客户端注册信息、令牌——已加密）保存在 Redis 中，以便在重启后保留，并支持多个副本。
PEARCH_MCP_OAUTH_REDIS_HOST / REDIS_ENDPOINT、REDIS_PORT、PEARCH_MCP_OAUTH_REDIS_DB、REDIS_PASSWORD	—、6379、4、—	OAuth 存储使用的 Redis 连接配置。
PEARCH_MCP_ALLOWED_CLIENT_REDIRECT_URIS	内置列表	MCP 客户端重定向 URI 的逗号分隔 fnmatch 模式（* = 任意值）。
PEARCH_MCP_TOKEN_CACHE_TTL_S	300	已验证身份的缓存 TTL；同时也是撤销延迟。
PEARCH_API_URL	https://api.pearch.ai	Pearch API 基础 URL（每次调用的 base_url 可覆盖此值）。
PEARCH_API_KEY	test_mcp_key	stdio/本地使用的回退密钥。
MCP_DISABLE_AUTH	—	1 等同于 PEARCH_MCP_AUTH=none（仅限本地开发）。

向 Pearch API 发出的工具请求在 POST 和 GET 调用中都会包含 X-Pearch-Source: mcp，包括人员搜索、公司潜在客户搜索、分页和个人资料补充。配置了内部密钥且目标源与 PEARCH_API_URL 匹配时，托管服务还会发送 X-Pearch-Source-Signature。HMAC 会绑定承载凭据、方法、解码后的路径与原始查询、正文及时间戳。后端接受 300 秒内的签名，因此服务端时钟必须保持同步。调用方提供的、指向其他源的 base_url 值不会获得签名。

后端会将已验证的 MCP 流量记录为 api_calls.request_source，用于分析和 DevAdmin 历史记录。仅有来源标头并不足够。使用 API 密钥的未签名自托管 MCP 流量仍会被归类为 api；经过身份验证且位于允许列表中的 OAuth 客户端无需标头即可识别。启用后端来源日志记录前，请先部署签名功能并应用其数据库迁移。较旧的后端会忽略这些标头。身份验证、账户归因和计费均不受影响。

在 oauth 模式下，入口/反向代理必须将整个主机路由到此服务，而不能仅路由 /mcp：此流程还会使用 /.well-known/oauth-*、/authorize、/token、/register、/revoke、/consent 和 /auth/callback。

开发

export PEARCH_API_KEY='test_mcp_key'   # or your key for full results
fastmcp dev inspector pearch_mcp.py

隐私政策

Pearch.AI 的隐私政策：https://pearch.ai/privacy-policy — 涵盖数据收集、使用、存储、第三方共享、保留期限和联系信息。数据删除/选择退出：https://pearch.ai/opt-out。服务条款：https://pearch.ai/tos。

支持

• 提交问题
• [email protected]

许可证

MIT — 参见 LICENSE。