Pearch

Pearch.ai MCP

MCP-Server für Pearch.AI: Natural-Language-Suche über Personen und Unternehmen/Leads (B2B). Nutzbar aus Claude, Cursor, VS Code oder jedem MCP-kompatiblen Client.

Evaluating AI Recruitment Sourcing Tools by Human Preference

Tools

Tool	Beschreibung
search_people	Personensuche mit einer Natural-Language-query oder strukturierten search_requirements. Unterstützt die Suchtypen fast/pro/superfast, Kontaktfreigabe & Kontaktfilter, Echtzeit-Profilaktualisierung, Insights sowie thread-basierte Paginierung/Follow-ups.
search_company_leads	Unternehmen und Leads/Kontakte darin finden (B2B). Beispiel: Unternehmen „AI startups in SF, 50–200 employees" + Leads „CTOs and engineering managers", mit optionalen personalisierten Outreach-Nachrichten.
get_profile	Eine einzelne Person anhand des LinkedIn-Slugs oder der E-Mail nachschlagen und anreichern (Kontaktfreigabe, Echtzeit-Aktualisierung, GitHub-Anreicherung).
get_user_info	Informationen zum authentifizierten Nutzer: E-Mail, verbleibende Credits, Preistarif. Kostenlos.

Strukturierte Personensuche

Übergebe search_requirements an search_people, wenn bereits eine Liste von Kriterien vorliegt:

{
  "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: erforderlich, nicht leerer Text. Halte jedes Kriterium kurz und eigenständig.
• must_have: true für Pflichtkriterien, false für wünschenswerte Präferenzen (der Standard).

Die Liste muss mindestens eine Anforderung enthalten. query ist optional, wenn search_requirements verwendet wird; werden beide angegeben, gibt die API search_requirements den Vorrang. Siehe den Pearch search API contract.

Beide Eingaben unterstützen dieselben Suchoptionen: Suchtyp, Insights und Scoring, Profilaktualisierung, Kontaktfreigabe und -filter, strikte Filterung, Ergebnisse mit geringer Konfidenz, Zeitbudget, Paginierung, Antwortfelder, Profilausschlüsse und kostenlose maskierte Ergebnisse. Die Einschränkungen der Suchtypen sind für beide Eingaben gleich; zum Beispiel unterstützt superfast keine Insights, kein Profil-Scoring und keine hohe Aktualität.

Für die Paginierung sende den zurückgegebenen thread_id mit limit und optional offset, ohne query und search_requirements. Um die Kriterien zu ändern, starte eine neue Suche ohne thread_id. Bestehende query-Aufrufe und Thread-Follow-ups werden weiterhin wie bisher weitergeleitet; die API entscheidet, welche Follow-up-Parameter sie akzeptiert.

custom_filters wird von diesem MCP-Server nicht bereitgestellt. Drücke Kriterien stattdessen in query oder search_requirements aus.

Remote-Server (empfohlen)

Der gehostete Server läuft unter https://mcp.pearch.ai/mcp und unterstützt zwei Authentifizierungsschemata gleichzeitig:

OAuth (keine Schlüsselverwaltung)

Füge den Server ohne Header hinzu — OAuth-fähige Clients (Claude, Cursor, VS Code) erkennen den Ablauf automatisch und öffnen eine Google-Anmeldung. Melde dich mit dem Google-Konto an, dessen E-Mail-Adresse mit deinem Pearch-Konto übereinstimmt:

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

Deine Suchen werden mit Credits von deinem eigenen Pearch-Konto abgerechnet. Falls dein Pearch-Konto noch keinen API-Schlüssel hat, erstelle zuerst einen im Pearch.ai Dashboard.

API-Schlüssel

Übergebe denselben Pearch-API-Schlüssel als api.pearch.ai:

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

Verwende test_mcp_key für maskierte (Beispiel-)Ergebnisse — keine Registrierung erforderlich.

Lokale Installation (stdio)

Erfordert Python 3.10+ und pip install -r requirements.txt (oder pip install fastmcp).

Claude Desktop / Claude Code

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

Oder manuell unter 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

Ersetze test_mcp_key durch deinen Dashboard-Schlüssel für vollständige Ergebnisse.

Eigenen HTTP-Server betreiben

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

Health: GET /health oder /healthcheck (meldet den Authentifizierungsmodus).

Umgebungsvariablen

Variable	Standard	Zweck
PEARCH_MCP_AUTH	api_key	oauth | api_key | none. Im Modus oauth werden rohe API-Key-Bearer weiterhin akzeptiert (Dual-Auth).
PEARCH_MCP_BASE_URL	http://localhost:8000	Öffentliche URL dieses Servers. OAuth-Metadaten, Token-Audience und die Redirect-URI /auth/callback leiten sich alle daraus ab.
PEARCH_MCP_GOOGLE_CLIENT_ID / PEARCH_MCP_GOOGLE_CLIENT_SECRET	—	Google OAuth 2.0 Web-Application-Client (registriere <base_url>/auth/callback als Redirect-URI). Erforderlich im Modus oauth.
PEARCH_MCP_INTERNAL_TOKEN	—	Gemeinsames Geheimnis für internes E-Mail→API-Key-Mapping und Signierung der Anfragequelle. Erforderlich im Modus oauth und für verifizierte MCP-Zuordnung mit API-Schlüsseln. Muss mit dem MCP_INTERNAL_TOKEN des Backends übereinstimmen; niemals an Endnutzer weitergeben.
PEARCH_MCP_OAUTH_STORE	disk	redis speichert den OAuth-Status (Client-Registrierungen, Tokens — verschlüsselt) in Redis, sodass er Neustarts übersteht und mehr als 1 Replica erlaubt.
PEARCH_MCP_OAUTH_REDIS_HOST / REDIS_ENDPOINT, REDIS_PORT, PEARCH_MCP_OAUTH_REDIS_DB, REDIS_PASSWORD	—, 6379, 4, —	Redis-Verbindung für den OAuth-Store.
PEARCH_MCP_ALLOWED_CLIENT_REDIRECT_URIS	integrierte Liste	Kommagetrennte fnmatch-Muster für Redirect-URIs von MCP-Clients (* = beliebig).
PEARCH_MCP_TOKEN_CACHE_TTL_S	300	TTL des Caches für verifizierte Identitäten; zugleich die Verzögerung bei Widerruf.
PEARCH_API_URL	https://api.pearch.ai	Pearch-API-Basis (pro Aufruf überschreibbar durch base_url).
PEARCH_API_KEY	test_mcp_key	Fallback-Schlüssel für stdio/lokale Nutzung.
MCP_DISABLE_AUTH	—	1 entspricht PEARCH_MCP_AUTH=none (nur lokale Entwicklung).

Tool-Anfragen an die Pearch-API enthalten X-Pearch-Source: mcp bei sowohl POST- als auch GET-Aufrufen, einschließlich Personensuche, Company-Leads-Suche, Paginierung und Profilanreicherung. Der gehostete Server sendet außerdem X-Pearch-Source-Signature, wenn das interne Geheimnis konfiguriert ist und der Ziel-Origin mit PEARCH_API_URL übereinstimmt. Die HMAC bindet die Bearer-Anmeldedaten, die Methode, den dekodierten Pfad samt roher Query, den Body und den Zeitstempel. Das Backend akzeptiert Signaturen innerhalb von 300 Sekunden, daher müssen die Server-Uhren synchronisiert sein. Vom Aufrufer gelieferte base_url-Werte bei anderen Origins erhalten keine Signatur.

Das Backend zeichnet verifizierten MCP-Traffic als api_calls.request_source für Analysen und DevAdmin-Verlauf auf. Ein bloßer Source-Header reicht nicht aus. Unsigned selbst gehosteter MCP-Traffic mit API-Schlüsseln bleibt api; authentifizierte, auf der Allowlist stehende OAuth-Clients werden ohne Header erkannt. Stelle die Signierung bereit, bevor du die Backend-Source-Protokollierung aktivierst, nachdem du deren Datenbank- Migration angewendet hast. Ältere Backends ignorieren die Header. Authentifizierung, Kontozuordnung und Abrechnung bleiben unverändert.

Im Modus oauth muss der Ingress/Reverse-Proxy den gesamten Host an den Server weiterleiten, nicht nur /mcp: Der Ablauf fügt /.well-known/oauth-*, /authorize, /token, /register, /revoke, /consent und /auth/callback hinzu.

Entwicklung

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

Datenschutzerklärung

Datenschutzerklärung von Pearch.AI: https://pearch.ai/privacy-policy — deckt Datenerhebung, -nutzung, -speicherung, Weitergabe an Dritte, Aufbewahrung und Kontaktinformationen ab. Datenlöschung / Opt-out: https://pearch.ai/opt-out. Nutzungsbedingungen: https://pearch.ai/tos.

Support

• Open an issue
• f@pearch.ai

Lizenz

MIT — siehe LICENSE.