Pearch

Pearch.ai MCP

Pearch.AI용 MCP 서버: 사람 및 회사/리드(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 슬러그 또는 이메일로 단일 인물을 조회하고 보강합니다(연락처 공개, 실시간 새로고침, GitHub 보강).
get_user_info	인증된 사용자 정보: 이메일, 남은 크레딧, 요금제. 무료.

구조화된 인물 검색

이미 기준 목록이 있는 경우 search_people에 search_requirements를 전달하세요:

{
  "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가 허용하는 후속 매개변수를 결정합니다.

custom_filters은 이 MCP 서버에서 노출되지 않습니다. 대신 기준을 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 Dashboard에서 먼저 생성하세요.

API 키

동일한 Pearch API 키를 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 모드에서는 원시 API 키 베어러도 여전히 허용됩니다(이중 인증).
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 웹 애플리케이션 클라이언트(<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	내장 목록	MCP 클라이언트 리디렉션 URI용 쉼표로 구분된 fnmatch 패턴(* = 모두).
PEARCH_MCP_TOKEN_CACHE_TTL_S	300	검증된 신원 캐시 TTL; 폐기 지연이기도 합니다.
PEARCH_API_URL	https://api.pearch.ai	Pearch API 기본 URL(호출별 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은 베어러 자격 증명, 메서드, 디코딩된 경로 및 원시 쿼리, 본문, 타임스탬프를 바인딩합니다. 백엔드는 300초 이내의 서명을 허용하므로 서버 시계가 동기화되어야 합니다. 다른 오리진에서 호출자가 제공한 base_url 값은 서명을 받지 않습니다.

백엔드는 검증된 MCP 트래픽을 분석 및 DevAdmin 기록을 위해 api_calls.request_source로 기록합니다. 소스 헤더만으로는 충분하지 않습니다. 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 — 데이터 수집, 사용, 저장, 제3자 공유, 보존, 연락처 정보를 다룹니다. 데이터 삭제 / 옵트아웃: https://pearch.ai/opt-out. 서비스 약관: https://pearch.ai/tos.

지원

• 이슈 열기
• f@pearch.ai

라이선스

MIT — LICENSE 참조.