Pearch

Pearch.ai MCP

Server MCP untuk Pearch.AI: pencarian bahasa alami atas orang dan perusahaan/lead (B2B). Gunakan dari Claude, Cursor, VS Code, atau klien apa pun yang kompatibel dengan MCP.

Evaluating AI Recruitment Sourcing Tools by Human Preference

Alat

Alat	Deskripsi
search_people	Pencarian orang dengan query bahasa alami atau search_requirements terstruktur. Mendukung tipe pencarian fast/pro/superfast, pengungkapan kontak & filter kontak, penyegaran profil real-time, insight, serta paginasi/tindak lanjut berbasis thread.
search_company_leads	Temukan perusahaan dan lead/kontak di dalamnya (B2B). Contoh: perusahaan "AI startups in SF, 50–200 employees" + lead "CTOs and engineering managers", dengan pesan outreach yang dipersonalisasi sebagai opsi.
get_profile	Cari dan perkaya satu orang berdasarkan slug LinkedIn atau email (pengungkapan kontak, penyegaran real-time, pengayaan GitHub).
get_user_info	Info pengguna terautentikasi: email, sisa kredit, paket harga. Gratis.

Pencarian orang terstruktur

Berikan search_requirements ke search_people jika Anda sudah memiliki daftar kriteria:

{
  "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: wajib, teks tidak boleh kosong. Jaga setiap kriteria tetap singkat dan mandiri.
• must_have: true untuk kriteria wajib, false untuk preferensi nice-to-have (default).

Daftar harus berisi setidaknya satu persyaratan. query bersifat opsional saat menggunakan search_requirements; jika keduanya diberikan, API memberi prioritas pada search_requirements. Lihat kontrak API pencarian Pearch.

Kedua input mendukung opsi pencarian yang sama: tipe pencarian, insight dan penilaian, penyegaran profil, pengungkapan dan filter kontak, penyaringan ketat, hasil dengan keyakinan rendah, batas waktu, paginasi, field respons, pengecualian profil, dan hasil masked gratis. Pembatasan tipe pencarian sama untuk kedua input; misalnya, superfast tidak mendukung insight, penilaian profil, atau kesegaran tinggi.

Untuk paginasi, kirim thread_id yang dikembalikan bersama limit dan opsional offset, dengan menghilangkan query dan search_requirements. Untuk mengubah kriteria, mulai pencarian baru tanpa thread_id. Panggilan query yang sudah ada dan tindak lanjut thread tetap diteruskan seperti sebelumnya; API yang menentukan parameter tindak lanjut mana yang diterima.

custom_filters tidak diekspos oleh server MCP ini. Ungkapkan kriteria dalam query atau search_requirements sebagai gantinya.

Server remote (disarankan)

Server yang dihosting berada di https://mcp.pearch.ai/mcp dan mendukung dua skema autentikasi sekaligus:

OAuth (tanpa penanganan kunci)

Tambahkan server tanpa header apa pun — klien yang mendukung OAuth (Claude, Cursor, VS Code) menemukan alur secara otomatis dan membuka login Google. Masuk dengan akun Google yang emailnya cocok dengan akun Pearch Anda:

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

Pencarian Anda menagih kredit ke akun Pearch Anda sendiri. Jika akun Pearch Anda belum memiliki API key, buat terlebih dahulu di Pearch.ai Dashboard.

API key

Berikan API key Pearch yang sama sebagai api.pearch.ai:

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

Gunakan test_mcp_key untuk hasil masked (sampel) — tidak perlu mendaftar.

Instalasi lokal (stdio)

Memerlukan Python 3.10+ dan pip install -r requirements.txt (atau pip install fastmcp).

Claude Desktop / Claude Code

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

Atau secara manual di bawah 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

Ganti test_mcp_key dengan kunci dashboard Anda untuk hasil lengkap.

Menjalankan server HTTP Anda sendiri

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

Health: GET /health atau /healthcheck (melaporkan mode autentikasi).

Variabel lingkungan

Variabel	Default	Tujuan
PEARCH_MCP_AUTH	api_key	oauth | api_key | none. Dalam mode oauth, bearer API-key mentah tetap diterima (autentikasi ganda).
PEARCH_MCP_BASE_URL	http://localhost:8000	URL publik server ini. Metadata OAuth, audiens token, dan URI redirect /auth/callback semuanya diturunkan darinya.
PEARCH_MCP_GOOGLE_CLIENT_ID / PEARCH_MCP_GOOGLE_CLIENT_SECRET	—	Klien Google OAuth 2.0 Web application (daftarkan <base_url>/auth/callback sebagai URI redirect). Wajib dalam mode oauth.
PEARCH_MCP_INTERNAL_TOKEN	—	Rahasia bersama untuk pemetaan internal email→API-key dan penandatanganan sumber permintaan. Wajib dalam mode oauth dan untuk atribusi MCP terverifikasi dengan API key. Harus cocok dengan MCP_INTERNAL_TOKEN milik backend; jangan pernah dibagikan ke pengguna akhir.
PEARCH_MCP_OAUTH_STORE	disk	redis menyimpan state OAuth (registrasi klien, token — terenkripsi) di Redis agar bertahan dari restart dan memungkinkan >1 replika.
PEARCH_MCP_OAUTH_REDIS_HOST / REDIS_ENDPOINT, REDIS_PORT, PEARCH_MCP_OAUTH_REDIS_DB, REDIS_PASSWORD	—, 6379, 4, —	Koneksi Redis untuk penyimpanan OAuth.
PEARCH_MCP_ALLOWED_CLIENT_REDIRECT_URIS	daftar bawaan	Pola fnmatch dipisahkan koma untuk URI redirect klien MCP (* = apa saja).
PEARCH_MCP_TOKEN_CACHE_TTL_S	300	TTL cache identitas terverifikasi; juga jeda pencabutan.
PEARCH_API_URL	https://api.pearch.ai	Basis API Pearch (base_url per panggilan menimpa).
PEARCH_API_KEY	test_mcp_key	Kunci cadangan untuk penggunaan stdio/lokal.
MCP_DISABLE_AUTH	—	1 setara dengan PEARCH_MCP_AUTH=none (hanya pengembangan lokal).

Permintaan alat ke API Pearch menyertakan X-Pearch-Source: mcp pada panggilan POST dan GET, termasuk pencarian orang, pencarian lead perusahaan, paginasi, dan pengayaan profil. Server yang dihosting juga mengirim X-Pearch-Source-Signature saat rahasia internal dikonfigurasi dan origin tujuan cocok dengan PEARCH_API_URL. HMAC mengikat kredensial bearer, metode, path yang didekode plus query mentah, body, dan timestamp. Backend menerima tanda tangan dalam 300 detik, sehingga jam server harus tersinkronisasi. Nilai base_url yang diberikan pemanggil pada origin lain tidak menerima tanda tangan.

Backend mencatat lalu lintas MCP terverifikasi sebagai api_calls.request_source untuk analitik dan riwayat DevAdmin. Header sumber saja tidak cukup. Lalu lintas MCP self-hosted tanpa tanda tangan yang menggunakan API key tetap api; klien OAuth terautentikasi yang masuk allowlist dikenali tanpa header. Terapkan penandatanganan sebelum mengaktifkan pencatatan sumber backend, setelah menerapkan migrasi database-nya. Backend lama mengabaikan header tersebut. Autentikasi, atribusi akun, dan penagihan tidak berubah.

Dalam mode oauth, ingress/reverse proxy harus merutekan seluruh host ke server, bukan hanya /mcp: alur ini menambahkan /.well-known/oauth-*, /authorize, /token, /register, /revoke, /consent, dan /auth/callback.

Pengembangan

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

Kebijakan Privasi

Kebijakan privasi Pearch.AI: https://pearch.ai/privacy-policy — mencakup pengumpulan data, penggunaan, penyimpanan, berbagi dengan pihak ketiga, retensi, dan informasi kontak. Penghapusan data / opt-out: https://pearch.ai/opt-out. Ketentuan layanan: https://pearch.ai/tos.

Dukungan

• Buka issue
• f@pearch.ai

Lisensi

MIT — lihat LICENSE.