Pearch

Pearch.ai MCP

用于 Pearch.AI 的 MCP 服务器：对人物和公司/线索（B2B）进行自然语言搜索。可在 Claude、Cursor、VS Code 或任何兼容 MCP 的客户端中使用。

Evaluating AI Recruitment Sourcing Tools by Human Preference

工具

工具	描述
search_people	使用自然语言 query 或结构化 search_requirements 进行人物搜索。支持 fast/pro/superfast 搜索类型、联系方式揭示与联系方式筛选、实时资料刷新、洞察，以及基于线程的分页/追问。
search_company_leads	查找公司及其中的线索/联系人（B2B）。示例：公司 "AI startups in SF, 50–200 employees" + 线索 "CTOs and engineering managers"，可选附带个性化外联消息。
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 密钥，请先在 Pearch.ai Dashboard 中创建一个。

API 密钥

将同一个 Pearch API 密钥作为 api.pearch.ai 传入：

{
  "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 密钥 bearer（双重认证）。
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 中，以便在重启后保留并支持多于 1 个副本。
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 基础地址（每次调用的 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 绑定 bearer 凭据、 方法、解码路径加原始查询、请求体和时间戳。后端接受 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.

支持

• 提交 issue
• f@pearch.ai

许可证

MIT —— 参见 LICENSE。