Pearch

Pearch.ai MCP

MCP-сервер для Pearch.AI: поиск на естественном языке по людям и компаниям/лидам (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-слагу или email (раскрытие контактов, обновление в реальном времени, обогащение данными GitHub).
get_user_info	Информация об аутентифицированном пользователе: email, оставшиеся кредиты, тарифный план. Бесплатно.

Структурированный поиск людей

Передайте 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 для желательных предпочтений (по умолчанию).

Список должен содержать хотя бы одно требование. query необязателен при использовании search_requirements; если указаны оба, API отдаёт приоритет search_requirements. См. Pearch search API contract.

Оба варианта ввода поддерживают одни и те же параметры поиска: тип поиска, инсайты и скоринг, обновление профиля, раскрытие контактов и фильтры, строгую фильтрацию, результаты с низкой уверенностью, лимит времени, пагинацию, поля ответа, исключения профилей и бесплатные маскированные результаты. Ограничения по типу поиска одинаковы для обоих вариантов ввода; например, superfast не поддерживает инсайты, скоринг профилей или высокую свежесть.

Для пагинации отправьте возвращённый thread_id вместе с limit и, опционально, offset, опустив query и search_requirements. Чтобы изменить критерии, начните новый поиск без thread_id. Существующие вызовы query и уточнения в рамках треда по-прежнему передаются как раньше; API решает, какие параметры уточнения он принимает.

custom_filters не предоставляется этим MCP-сервером. Выражайте критерии через query или search_requirements.

Удалённый сервер (рекомендуется)

Хостинговый сервер находится по адресу https://mcp.pearch.ai/mcp и поддерживает две схемы аутентификации одновременно:

OAuth (без работы с ключами)

Добавьте сервер без каких-либо заголовков — клиенты с поддержкой OAuth (Claude, Cursor, VS Code) автоматически обнаруживают поток и открывают вход через Google. Войдите с помощью аккаунта Google, email которого совпадает с вашим аккаунтом Pearch:

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

Ваши поисковые запросы списывают кредиты с вашего собственного аккаунта Pearch. Если у вашего аккаунта Pearch ещё нет API-ключа, сначала создайте его в Pearch.ai Dashboard.

API-ключ

Передайте тот же API-ключ Pearch в качестве 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 необработанные bearer-токены API-ключей по-прежнему принимаются (двойная аутентификация).
PEARCH_MCP_BASE_URL	http://localhost:8000	Публичный URL этого сервера. Метаданные OAuth, аудитория токена и redirect URI /auth/callback выводятся из него.
PEARCH_MCP_GOOGLE_CLIENT_ID / PEARCH_MCP_GOOGLE_CLIENT_SECRET	—	Клиент Google OAuth 2.0 Web application (зарегистрируйте <base_url>/auth/callback как redirect URI). Обязательно в режиме oauth.
PEARCH_MCP_INTERNAL_TOKEN	—	Общий секрет для внутреннего сопоставления email→API-ключ и подписи источника запроса. Обязателен в режиме oauth и для проверенной атрибуции MCP с API-ключами. Должен совпадать с MCP_INTERNAL_TOKEN бэкенда; никогда не распространяйте его среди конечных пользователей.
PEARCH_MCP_OAUTH_STORE	disk	redis хранит состояние OAuth (регистрации клиентов, токены — в зашифрованном виде) в Redis, чтобы оно переживало перезапуски и допускало более одной реплики.
PEARCH_MCP_OAUTH_REDIS_HOST / REDIS_ENDPOINT, REDIS_PORT, PEARCH_MCP_OAUTH_REDIS_DB, REDIS_PASSWORD	—, 6379, 4, —	Подключение к Redis для хранилища OAuth.
PEARCH_MCP_ALLOWED_CLIENT_REDIRECT_URIS	встроенный список	Разделённые запятыми шаблоны fnmatch для redirect URI MCP-клиентов (* = любой).
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 включают X-Pearch-Source: mcp как в POST-, так и в GET-вызовах, включая поиск людей, поиск лидов компаний, пагинацию и обогащение профилей. Хостинговый сервер также отправляет X-Pearch-Source-Signature, когда настроен внутренний секрет и origin назначения совпадает с PEARCH_API_URL. HMAC связывает bearer-учётные данные, метод, декодированный путь вместе с необработанным запросом, тело и временную метку. Бэкенд принимает подписи в пределах 300 секунд, поэтому часы серверов должны быть синхронизированы. Предоставленные вызывающей стороной значения base_url на других origin не получают подписи.

Бэкенд записывает проверенный трафик MCP как api_calls.request_source для аналитики и истории DevAdmin. Одного заголовка источника недостаточно. Неподписанный трафик самостоятельно размещённого MCP с использованием API-ключей остаётся api; аутентифицированные клиенты OAuth из белого списка распознаются без заголовков. Разверните подпись до включения логирования источника на бэкенде, после применения его миграции базы данных. Старые бэкенды игнорируют заголовки. Аутентификация, атрибуция аккаунта и биллинг не меняются.

В режиме oauth ingress/обратный прокси должен направлять весь хост на сервер, а не только /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.

Поддержка

• Open an issue
• f@pearch.ai

Лицензия

MIT — см. LICENSE.