Pearch

Pearch.ai MCP

Servidor MCP para Pearch.AI: búsqueda en lenguaje natural sobre personas y empresas/leads (B2B). Úsalo desde Claude, Cursor, VS Code o cualquier cliente compatible con MCP.

Evaluating AI Recruitment Sourcing Tools by Human Preference

Herramientas

Herramienta	Descripción
search_people	Búsqueda de personas con una query en lenguaje natural o un search_requirements estructurado. Admite tipos de búsqueda fast/pro/superfast, revelación de contactos y filtros de contacto, actualización de perfiles en tiempo real, insights y paginación/seguimientos basados en hilos.
search_company_leads	Encuentra empresas y leads/contactos dentro de ellas (B2B). Ejemplo: empresa "startups de IA en SF, 50–200 empleados" + leads "CTOs y engineering managers", con mensajes de contacto personalizados opcionales.
get_profile	Busca y enriquece una sola persona por slug de LinkedIn o correo electrónico (revelación de contactos, actualización en tiempo real, enriquecimiento con GitHub).
get_user_info	Información del usuario autenticado: correo electrónico, créditos restantes, plan de precios. Gratis.

Búsqueda estructurada de personas

Pasa search_requirements a search_people cuando ya tengas una lista de criterios:

{
  "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: obligatorio, texto no vacío. Mantén cada criterio breve y autocontenido.
• must_have: true para criterios obligatorios, false para preferencias deseables (el valor predeterminado).

La lista debe contener al menos un requisito. query es opcional cuando se usa search_requirements; si se proporcionan ambos, la API da precedencia a search_requirements. Consulta el contrato de la API de búsqueda de Pearch.

Ambas entradas admiten las mismas opciones de búsqueda: tipo de búsqueda, insights y puntuación, actualización de perfiles, revelación de contactos y filtros, filtrado estricto, resultados de baja confianza, presupuesto de tiempo, paginación, campos de respuesta, exclusiones de perfiles y resultados enmascarados gratuitos. Las restricciones del tipo de búsqueda son las mismas para ambas entradas; por ejemplo, superfast no admite insights, puntuación de perfiles ni alta frescura.

Para la paginación, envía el thread_id devuelto con limit y, opcionalmente, offset, omitiendo query y search_requirements. Para cambiar los criterios, inicia una nueva búsqueda sin thread_id. Las llamadas existentes a query y los seguimientos de hilos se siguen reenviando como antes; la API decide qué parámetros de seguimiento acepta.

custom_filters no está expuesto por este servidor MCP. Expresa los criterios en query o search_requirements en su lugar.

Servidor remoto (recomendado)

El servidor alojado se encuentra en https://mcp.pearch.ai/mcp y admite dos esquemas de autenticación a la vez:

OAuth (sin manejo de claves)

Añade el servidor sin encabezados: los clientes compatibles con OAuth (Claude, Cursor, VS Code) descubren el flujo automáticamente y abren un inicio de sesión de Google. Inicia sesión con la cuenta de Google cuyo correo electrónico coincida con tu cuenta de Pearch:

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

Tus búsquedas consumen créditos de tu propia cuenta de Pearch. Si tu cuenta de Pearch aún no tiene una clave de API, crea una primero en el Panel de Pearch.ai.

Clave de API

Pasa la misma clave de API de Pearch como api.pearch.ai:

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

Usa test_mcp_key para obtener resultados enmascarados (de muestra) — no se requiere registro.

Instalación local (stdio)

Requiere Python 3.10+ y pip install -r requirements.txt (o pip install fastmcp).

Claude Desktop / Claude Code

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

O manualmente en 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

Reemplaza test_mcp_key con la clave de tu panel para obtener resultados completos.

Ejecutar tu propio servidor HTTP

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

Estado: GET /health o /healthcheck (informa el modo de autenticación).

Variables de entorno

Variable	Predeterminado	Propósito
PEARCH_MCP_AUTH	api_key	oauth | api_key | none. En modo oauth todavía se aceptan portadores de clave de API sin procesar (autenticación dual).
PEARCH_MCP_BASE_URL	http://localhost:8000	URL pública de este servidor. Los metadatos de OAuth, la audiencia del token y el URI de redirección /auth/callback se derivan de ella.
PEARCH_MCP_GOOGLE_CLIENT_ID / PEARCH_MCP_GOOGLE_CLIENT_SECRET	—	Cliente de aplicación web de Google OAuth 2.0 (registra <base_url>/auth/callback como URI de redirección). Obligatorio en modo oauth.
PEARCH_MCP_INTERNAL_TOKEN	—	Secreto compartido para el mapeo interno de correo electrónico→clave de API y la firma del origen de la solicitud. Obligatorio en modo oauth y para la atribución verificada de MCP con claves de API. Debe coincidir con el MCP_INTERNAL_TOKEN del backend; nunca lo distribuyas a los usuarios finales.
PEARCH_MCP_OAUTH_STORE	disk	redis mantiene el estado de OAuth (registros de clientes, tokens — cifrados) en Redis para que sobreviva a los reinicios y permita más de 1 réplica.
PEARCH_MCP_OAUTH_REDIS_HOST / REDIS_ENDPOINT, REDIS_PORT, PEARCH_MCP_OAUTH_REDIS_DB, REDIS_PASSWORD	—, 6379, 4, —	Conexión de Redis para el almacén de OAuth.
PEARCH_MCP_ALLOWED_CLIENT_REDIRECT_URIS	lista integrada	Patrones fnmatch separados por comas para los URI de redirección de clientes MCP (* = cualquiera).
PEARCH_MCP_TOKEN_CACHE_TTL_S	300	TTL de la caché de identidad verificada; también el retraso de revocación.
PEARCH_API_URL	https://api.pearch.ai	Base de la API de Pearch (las base_url por llamada la anulan).
PEARCH_API_KEY	test_mcp_key	Clave de respaldo para uso local/stdio.
MCP_DISABLE_AUTH	—	1 es equivalente a PEARCH_MCP_AUTH=none (solo desarrollo local).

Las solicitudes de herramientas a la API de Pearch incluyen X-Pearch-Source: mcp tanto en llamadas POST como GET, incluyendo búsqueda de personas, búsqueda de leads de empresas, paginación y enriquecimiento de perfiles. El servidor alojado también envía X-Pearch-Source-Signature cuando el secreto interno está configurado y el origen de destino coincide con PEARCH_API_URL. El HMAC vincula la credencial del portador, el método, la ruta decodificada más la consulta sin procesar, el cuerpo y la marca de tiempo. El backend acepta firmas dentro de 300 segundos, por lo que los relojes de los servidores deben estar sincronizados. Los valores de base_url proporcionados por el llamador en otros orígenes no reciben firma.

El backend registra el tráfico MCP verificado como api_calls.request_source para análisis y historial de DevAdmin. Un encabezado de origen sin procesar no es suficiente. El tráfico MCP autohospedado sin firma que usa claves de API sigue siendo api; los clientes OAuth autenticados en la lista de permitidos se reconocen sin encabezados. Despliega la firma antes de habilitar el registro de origen del backend, después de aplicar su migración de base de datos. Los backends más antiguos ignoran los encabezados. La autenticación, la atribución de cuentas y la facturación no cambian.

En modo oauth, el proxy de entrada/inverso debe enrutar el host completo al servidor, no solo /mcp: el flujo añade /.well-known/oauth-*, /authorize, /token, /register, /revoke, /consent y /auth/callback.

Desarrollo

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

Política de privacidad

Política de privacidad de Pearch.AI: https://pearch.ai/privacy-policy — cubre la recopilación de datos, el uso, el almacenamiento, el intercambio con terceros, la retención y la información de contacto. Eliminación de datos / exclusión: https://pearch.ai/opt-out. Términos de servicio: https://pearch.ai/tos.

Soporte

• Abrir un issue
• f@pearch.ai

Licencia

MIT — consulta LICENSE.