Pearch

Pearch.ai MCP

適用於 Pearch.AI 的 MCP 伺服器：以自然語言搜尋人物與公司/潛在客戶（B2B）。可從 Claude、Cursor、VS Code 或任何相容於 MCP 的用戶端使用。

以人類偏好評估 AI 招募人才搜尋工具

工具

工具	說明
search_people	以自然語言 query 或結構化 search_requirements 進行人物搜尋。支援 fast/pro/superfast 搜尋類型、聯絡資訊揭露與聯絡資訊篩選、即時個人檔案重新整理、洞察，以及以執行緒為基礎的分頁/後續追問。
search_company_leads	尋找公司及其中的潛在客戶/聯絡人（B2B）。範例：公司*「舊金山、50–200 名員工的 AI 新創公司」* + 潛在客戶*「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 金鑰，請先在 Pearch.ai 儀表板建立一個。

API 金鑰

以 api.pearch.ai 傳入相同的 Pearch API 金鑰：

{
  "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	內建清單	以逗號分隔的 fnmatch 模式，用於 MCP 用戶端重新導向 URI（* = 任意）。
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.

支援

• 開啟問題
• f@pearch.ai

授權

MIT — 請參閱 LICENSE。