BatchData MCP (Real Estate & Contact Data)

BatchData 원격 MCP 서버 설정 가이드

• 1 소개
• 2 인증 방법
  • 2.1 OAuth 인증 (권장)
  • 2.2 API 토큰 인증 (대안)
• 3 향후 개선 사항: OAuth 접근 제어 (곧 제공 예정)
• 4 OAuth 설정 (권장)
  • 4.1 사전 준비 사항
  • 4.2 Claude 설정 (데스크톱, 웹 및 모바일)
    • 4.2.1 1단계: BatchData 커넥터 추가
    • 4.2.2 2단계: 인증
    • 4.2.3 3단계: 커넥터 활성화
    • 4.2.4 4단계: 초기 도구 사용 승인
    • 4.2.5 모바일에서 사용하기
    • 4.2.6 후속 연결
  • 4.3 Cursor 설정
  • 4.4 Claude Code 설정
  • 4.5 ChatGPT 설정 (개발자 모드)
    • 4.5.1 사전 준비 사항
    • 4.5.2 1단계: 개발자 모드 활성화
    • 4.5.3 2단계: BatchData 커넥터 생성
    • 4.5.4 3단계: 인증
    • 4.5.5 ChatGPT에서 BatchData 도구 사용하기
    • 4.5.6 연결 관리
  • 4.6 확인
• 5 API 토큰 설정 (대안)
  • 5.1 사전 준비 사항
  • 5.2 API 토큰으로 Claude 데스크톱 설정
    • 5.2.1 1단계: Node.js 22 설치
    • 5.2.2 2단계: Claude 데스크톱 구성
  • 5.3 사용자 지정 MCP 클라이언트 설정
• 6 API 토큰에서 OAuth로 마이그레이션
  • 6.1 Claude 데스크톱
  • 6.2 Claude Code
  • 6.3 ChatGPT
  • 6.4 마이그레이션의 이점
• 7 사용 가능한 도구
  • 7.1 부동산 조회 및 세부 정보
  • 7.2 비교 부동산 분석
  • 7.3 부동산 검색
  • 7.4 연락처 정보
  • 7.5 전화번호 확인
  • 7.6 주소 처리
• 8 문제 해결
  • 8.1 OAuth 문제
  • 8.2 ChatGPT 문제
  • 8.3 API 토큰 문제
  • 8.4 일반 문제
  • 8.5 도움 받기

소개

이 가이드는 MCP 호환 클라이언트를 사용하여 BatchData 원격 MCP 서버에 연결하는 방법을 설명합니다.

인증 방법

BatchData MCP 서버는 두 가지 인증 방법을 지원합니다:

방법	설정 복잡성	보안	권장 대상
OAuth (권장)	간단함	높음	대부분의 사용자
API 토큰	수동 구성	보통	사용자 지정 MCP 클라이언트, 디버깅

OAuth 인증 (권장)

OAuth는 간소화된 연결 환경을 제공합니다:

• API 토큰 구성 불필요 — 서버 URL만 제공하면 됩니다.
• 브라우저 기반 로그인 — BatchData 계정 자격 증명으로 인증합니다.
• 자동 토큰 관리 — 액세스 토큰이 자동으로 갱신됩니다.
• 익숙한 로그인 환경 — 이메일/비밀번호 또는 Google 로그인을 사용합니다.

API 토큰 인증 (대안)

직접 API 토큰 구성을 선호하거나 OAuth를 지원하지 않는 사용자 지정 MCP 클라이언트를 사용하는 사용자를 위한 방법입니다:

• BatchData API 토큰을 수동으로 확보하고 구성해야 합니다.
• 토큰은 민감한 자격 증명으로 관리 및 보호되어야 합니다.
• 디버깅, 자동화 스크립트 또는 OAuth를 지원하지 않는 클라이언트에 유용합니다.

향후 개선 사항: OAuth 접근 제어 (곧 제공 예정)

OAuth 인증을 위한 향상된 접근 제어 기능을 개발 중입니다:

• 권한 확인 — OAuth 로그인 시 계정에 MCP 서버 사용 권한이 부여되었는지 자동으로 확인합니다.
• 중앙 집중식 접근 관리 — 팀 소유자는 BatchData 플랫폼을 통해 팀 구성원의 MCP 서버 접근 권한을 부여하거나 취소할 수 있습니다.

---

OAuth 설정 (권장)

사전 준비 사항

• 유효한 자격 증명이 있는 BatchData 계정
• MCP 호환 클라이언트 (Claude 데스크톱/웹/모바일, ChatGPT, Cursor, Claude Code 또는 유사 제품)

Claude 설정 (데스크톱, 웹 및 모바일)

Claude는 데스크톱 앱, 웹 인터페이스 및 모바일 앱을 통해 MCP 서버를 지원합니다.

모바일 참고 사항: 모바일 앱에서는 커넥터를 추가할 수 없습니다. 먼저 데스크톱 또는 웹에서 커넥터를 추가하면 동일한 계정의 모바일에서 자동으로 사용할 수 있습니다.

팀/엔터프라이즈 참고 사항: 작업 공간 관리자는 팀 구성원이 구성하기 전에 먼저 사용 가능한 커넥터 목록에 BatchData 커넥터를 추가해야 합니다. 목록에 커넥터가 보이지 않으면 관리자에게 문의하십시오.

1단계: BatchData 커넥터 추가

1. Claude를 엽니다 (데스크톱 또는 웹).
2. 설정 → 커넥터 (또는 설정 → MCP 서버)로 이동합니다.
3. 커넥터 추가 (또는 서버 추가)를 클릭합니다.
4. 서버 URL을 입력합니다:

https://mcp.batchdata.com

5. 추가 또는 연결을 클릭합니다.

2단계: 인증

1. 브라우저에 BatchData 로그인 페이지가 열립니다.
2. 다음 중 하나를 사용하여 로그인합니다:

• 이메일 및 비밀번호 — BatchData 계정 자격 증명을 입력합니다.
• Google 로그인 — Google 버튼을 클릭하여 인증합니다.

3. 로그인에 성공하면 Claude로 다시 리디렉션됩니다.

3단계: 커넥터 활성화

커넥터는 추가 후 기본적으로 활성화되지 않습니다. 한 번 활성화하면 설정이 저장됩니다:

1. 아무 채팅이나 엽니다.
2. 채팅 입력 영역에서 + 버튼 (또는 커넥터 아이콘)을 클릭합니다.
3. 사용 가능한 커넥터 목록에서 BatchData를 찾습니다.
4. 토글을 켜서 활성화합니다.

이제 모든 대화에서 커넥터를 사용할 수 있습니다.

4단계: 초기 도구 사용 승인

Claude가 BatchData 도구를 처음 사용할 때 승인을 요청받습니다:

1. Claude가 도구 사용을 시도하면 권한 프롬프트가 나타납니다.
2. 요청된 도구와 작업을 검토합니다.
3. 허용을 클릭하여 승인합니다.
4. 해당 도구의 향후 사용에 대한 승인을 건너뛰려면 **"항상 허용"**을 선택합니다.

참고: 초기 승인 (또는 "항상 허용" 선택) 후에는 후속 도구 사용 시 추가 확인이 필요하지 않습니다.

모바일에서 사용하기

데스크톱 또는 웹에서 커넥터를 추가하고 인증하면:

• 동일한 계정으로 Claude 모바일 앱을 엽니다.
• 커넥터 목록에서 BatchData 커넥터를 사용할 수 있습니다.
• 아직 활성화되지 않은 경우 채팅 입력의 + 버튼을 통해 토글을 켭니다 (설정은 기기 간에 동기화됨).
• 데스크톱/웹에서 부여된 도구 승인은 모바일에도 적용됩니다.
• 모든 도구는 데스크톱/웹과 동일하게 작동합니다.

후속 연결

초기 인증 후:

• 액세스 토큰은 캐시되며 모든 기기에서 자동으로 갱신됩니다.
• 세션이 만료되지 않는 한 (일반적으로 14일 동안 비활성 상태) 다시 로그인할 필요가 없습니다.
• 재인증하라는 메시지가 표시되면 브라우저를 통해 다시 로그인하면 됩니다 (데스크톱 또는 웹에서).

Cursor 설정

1. Cursor 설정을 엽니다.
2. MCP 구성 섹션으로 이동합니다.
3. MCP 서버 추가를 클릭합니다.
4. 서버 URL을 입력합니다:

https://mcp.batchdata.com

5. 처음 사용 시 브라우저 팝업을 통해 인증합니다.

Claude Code 설정

CLI를 통해 직접 BatchData MCP 서버를 추가합니다:

claude mcp add BatchData --url https://mcp.batchdata.com

처음 사용 시 브라우저를 통해 인증하라는 메시지가 표시됩니다.

ChatGPT 설정 (개발자 모드)

ChatGPT는 완전한 모델 컨텍스트 프로토콜 클라이언트 지원을 제공하는 개발자 모드를 통해 MCP 서버를 지원합니다.

사전 준비 사항

• ChatGPT Plus 또는 Pro 구독
• 비즈니스/엔터프라이즈의 경우: 관리자가 작업 공간 설정에서 개발자 모드를 활성화해야 합니다.

1단계: 개발자 모드 활성화

1. ChatGPT를 엽니다.
2. 설정 → 앱 및 커넥터 → 고급 설정으로 이동합니다.
3. 개발자 모드 토글을 켭니다.

비즈니스/엔터프라이즈 작업 공간의 경우:

• 관리자는 작업 공간 설정 → 권한 및 역할 → 연결된 데이터 → 개발자 모드 / 사용자 지정 MCP 커넥터 생성에서 먼저 개발자 모드를 활성화해야 합니다.

2단계: BatchData 커넥터 생성

1. ChatGPT에서 설정 → 커넥터로 이동합니다.
2. 생성을 클릭합니다.
3. 다음 세부 정보를 입력합니다:

• 커넥터 이름: BatchData
• MCP 서버 URL: https://mcp.batchdata.com

4. 생성을 클릭합니다.

3단계: 인증

1. 커넥터를 생성하면 ChatGPT가 인증하라는 메시지를 표시합니다.
2. 브라우저에 BatchData 로그인 페이지가 열립니다.
3. 다음 중 하나를 사용하여 로그인합니다:

• 이메일 및 비밀번호 — BatchData 계정 자격 증명을 입력합니다.
• Google 로그인 — Google 버튼을 클릭하여 인증합니다.

4. 로그인에 성공하면 ChatGPT로 다시 리디렉션됩니다.
5. 이제 BatchData 커넥터를 사용할 준비가 되었습니다.

ChatGPT에서 BatchData 도구 사용하기

연결되면 대화에서 BatchData 도구를 사용할 수 있습니다:

1. 새 채팅을 시작합니다.
2. + 버튼을 클릭한 다음 더 보기 메뉴에서 커넥터를 선택합니다.
3. 또는 플러스 메뉴에서 개발자 모드를 선택하고 BatchData를 선택합니다.
4. 부동산 관련 질문을 하면 ChatGPT가 적절한 도구를 사용합니다.

프롬프트 예시:

• "123 Main Street, Los Angeles, CA에 있는 부동산을 조회해 줘"
• "456 Oak Avenue의 비교 부동산을 찾아줘"
• "789 Pine Road, Miami, FL 소유주를 건너뛰기 추적해 줘"

연결 관리

• 연결 해제하려면: 설정 → 커넥터로 이동하여 BatchData를 클릭하고 연결 해제합니다.
• 다시 연결하려면: 커넥터를 클릭하고 재인증합니다.
• 세션 만료: 세션이 만료되면 (일반적으로 14일 후) 다시 연결하라는 메시지가 표시됩니다.

확인

연결되면 부동산 데이터나 건너뛰기 추적에 대해 질문하기만 하면 LLM이 자동으로 BatchData 도구를 사용합니다.

프롬프트 예시:

• "123 Main Street, Los Angeles, CA에 있는 부동산을 조회해 줘"
• "456 Oak Avenue, Miami, FL 소유주를 건너뛰기 추적해 줘"
• "789 Pine Road, Austin, TX의 비교 부동산을 찾아줘"
• "Miami, FL에서 공실 부동산을 검색해 줘"
• "이 전화번호를 확인해 줘: 555-123-4567"
• "이 주소를 확인하고 표준화해 줘: 100 main st los angeles ca"
• "200 Park Avenue, New York, NY의 좌표를 알려줘"

Claude 또는 ChatGPT는 의도를 인식하고 적절한 BatchData 도구를 사용하여 정보를 가져옵니다.

---

API 토큰 설정 (대안)

다음과 같은 경우 이 방법을 사용하십시오:

• MCP 클라이언트가 OAuth를 지원하지 않는 경우
• MCP 서버 연결을 디버깅하거나 자동화해야 하는 경우
• 명시적인 토큰 관리를 선호하는 경우

사전 준비 사항

• BatchData API 토큰 (BatchData 웹 앱에서 획득)
• MCP 호환 클라이언트
• Node.js 22+ (Claude 데스크톱용)

API 토큰으로 Claude 데스크톱 설정

1단계: Node.js 22 설치

Claude 데스크톱에 번들로 제공되는 Node.js는 오래되었습니다. Node.js 22를 별도로 설치하십시오:

macOS/Linux:

# Install Volta (Node.js version manager) curl https://get.volta.sh | bash # Restart terminal, then install Node.js 22 volta install node@22 # Find your username for the config below whoami

Windows:

nodejs.org에서 Node.js 22.x LTS를 다운로드하여 설치하십시오.

2단계: Claude 데스크톱 구성

1. Claude 데스크톱을 엽니다.
2. 설정 > 개발자 > 구성 편집으로 이동합니다.
3. 다음 구성을 추가합니다:

macOS 구성:

{ "mcpServers": { "BatchData": { "command": "/Users/YOUR_USERNAME/.volta/bin/npx", "args": [ "-y", "mcp-remote", "https://mcp.batchdata.com", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer YOUR_API_TOKEN_HERE" } } } }

Linux 구성:

{ "mcpServers": { "BatchData": { "command": "/home/YOUR_USERNAME/.volta/bin/npx", "args": [ "-y", "mcp-remote", "https://mcp.batchdata.com", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer YOUR_API_TOKEN_HERE" } } } }

Windows 구성:

{ "mcpServers": { "BatchData": { "command": "C:\\Program Files\\nodejs\\npx.cmd", "args": [ "-y", "mcp-remote", "https://mcp.batchdata.com", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer YOUR_API_TOKEN_HERE" } } } }

4. YOUR_USERNAME을 실제 사용자 이름으로 바꿉니다.
5. YOUR_API_TOKEN_HERE을 BatchData API 토큰으로 바꿉니다.
6. 파일을 저장하고 Claude 데스크톱을 다시 시작합니다.

사용자 지정 MCP 클라이언트 설정

사용자 지정 MCP 클라이언트 구현의 경우:

연결 세부 정보:

설정	값
서버 URL	https://mcp.batchdata.com
전송 방식	스트리밍 가능 HTTP
인증	Authorization 헤더를 통한 Bearer 토큰

구성 예시:

{ "server_url": "https://mcp.batchdata.com", "headers": { "Authorization": "Bearer YOUR_API_TOKEN_HERE" } }

npx 사용:

npx mcp-remote https://mcp.batchdata.com --header "Authorization:Bearer YOUR_API_TOKEN_HERE"

---

API 토큰에서 OAuth로 마이그레이션

이전에 API 토큰 방법을 사용하여 BatchData를 설정했고 더 간단한 환경을 위해 OAuth로 전환하려면 다음 단계를 따르십시오:

Claude 데스크톱

1. Claude Desktop 열기
2. 설정 → 개발자 → 구성 편집으로 이동
3. 기존 BatchData 구성 제거 (command, args, env가 포함된 전체 블록)
4. 구성 파일을 저장하고 닫기
5. Claude 설정 (데스크톱, 웹 및 모바일) 지침에 따라 UI를 통해 커넥터 추가
6. 메시지가 표시되면 BatchData 계정으로 인증

이전 (API 토큰):

{ "mcpServers": { "BatchData": { "command": "/Users/YOUR_USERNAME/.volta/bin/npx", "args": ["-y", "mcp-remote", "https://mcp.batchdata.com", "--header", "Authorization:${AUTH_HEADER}"], "env": { "AUTH_HEADER": "Bearer YOUR_API_TOKEN" } } } }

이후 (OAuth): UI를 통해 구성 — JSON 편집이 필요하지 않습니다.

Claude Code

1. 기존 구성 제거:

claude mcp remove BatchData

2. OAuth를 사용하여 다시 추가:

claude mcp add BatchData --url https://mcp.batchdata.com

3. 메시지가 표시되면 브라우저를 통해 인증

ChatGPT

API 토큰으로 해결 방법을 사용 중이었다면, 간단히:

1. 설정 → 커넥터에서 기존 BatchData 커넥터 제거
2. ChatGPT 설정 지침에 따라 새 커넥터 생성
3. BatchData 계정으로 인증

마이그레이션의 이점

측면	API 토큰	OAuth
설정	수동 JSON 편집	간단한 UI 흐름
토큰 관리	수동 갱신	자동 새로 고침
보안	구성 파일에 토큰 저장	클라이언트가 토큰 관리
멀티 디바이스	각 디바이스 구성	디바이스 간 동기화

---

사용 가능한 도구

연결되면 BatchData MCP 서버는 다음 도구를 제공합니다:

부동산 조회 및 세부 정보

도구	설명
lookup_property	ID, 주소 또는 지번으로 자세한 부동산 정보 가져오기

유사 부동산 분석

도구	설명
comparable_property_count	유사 부동산 수 및 집계 지표 가져오기
comparable_property_preview	요약 필드가 포함된 처음 10개 유사 부동산 빠른 미리 보기
comparable_property_page	전체 유사 부동산 세부 정보에 대한 페이지 매김 액세스 (오프셋 및 커서 기반 페이지 매김 모두 지원)
comparable_property	⚠️ 더 이상 사용되지 않음 — 모든 유사 부동산을 한 번에 반환

부동산 검색

도구	설명
search_properties_count	빠른 목록 분석과 함께 검색 기준과 일치하는 부동산 수 가져오기
search_properties_preview	처음 10개 일치 부동산 빠른 미리 보기
search_properties_page	전체 세부 정보가 포함된 페이지 매김 부동산 검색 (오프셋 및 커서 기반 페이지 매김 지원)

연락처 정보

도구	설명
skip_trace_property	주소 또는 지번으로 부동산 소유자 및 연락처 정보 가져오기

전화 확인

도구	설명
verify_phone	연결 가능성, DNC 상태, 통신사, TCPA 소송 당사자 상태를 포함한 전체 확인 세부 정보
check_dnc_status	수신 거부 목록 상태만 확인
check_tcpa_status	TCPA 소송 당사자 상태만 확인

주소 처리

도구	설명
verify_address	USPS 규정 준수에 맞게 주소 형식 지정
geocode_address	주소에서 좌표 가져오기
reverse_geocode_address	위도/경도 좌표에서 주소 가져오기

---

문제 해결

OAuth 문제

문제	해결책
로그인을 위해 브라우저가 열리지 않음	팝업이 허용되었는지 확인하세요. 기본 브라우저가 올바르게 설정되었는지 확인하세요.
로그인 페이지에 "세션이 만료되었습니다" 표시	커넥터를 제거하고 다시 추가한 다음 다시 인증하세요.
"로그인 시도 횟수 초과" 오류	다시 시도하기 전에 15분 동안 기다리세요.
Google 로그인이 작동하지 않음	팝업이 허용되었는지 확인하고 대신 이메일/비밀번호를 사용해 보세요.
로그인 후 연결 실패	인터넷 연결을 확인하세요. MCP 클라이언트로의 리디렉션이 실패했을 수 있습니다. 커넥터를 제거하고 다시 추가해 보세요.

ChatGPT 문제

문제	해결책
커넥터를 만들 수 없음	설정 → 앱 및 커넥터 → 고급 설정에서 개발자 모드가 활성화되었는지 확인하세요.
개발자 모드 토글 누락	Business/Enterprise의 경우 작업 공간 관리자가 먼저 작업 공간 설정에서 활성화해야 합니다.
인증 실패	http://chatgpt.com 에 대해 팝업이 허용되었는지 확인하세요. 커넥터 연결을 끊었다가 다시 연결해 보세요.
도구가 사용되지 않음	프롬프트에서 명시적으로 지정하세요: "BatchData 커넥터를 사용하여...". 프롬프트를 입력하기 전에 + 버튼을 통해 커넥터를 추가하세요.
커넥터가 응답하지 않음	설정 → 커넥터 → BatchData → 새로 고침으로 이동하여 메타데이터를 업데이트하세요. 서버가 일시적으로 사용 불가능할 수 있습니다.
잘못된 도구가 호출됨	지정하세요: "내장 브라우징 또는 다른 도구를 사용하지 말고 BatchData 커넥터만 사용하세요."

API 토큰 문제

문제	해결책
401 Unauthorized	API 토큰이 올바르고 만료되지 않았는지 확인하세요.
403 Forbidden	토큰에 BatchData 웹 앱에서 필요한 엔드포인트 권한이 있는지 확인하세요.
Node.js 경로 오류	which npx (macOS/Linux)를 실행하거나 설치 경로(Windows)를 확인하여 npx 경로가 존재하는지 확인하세요.
구성이 로드되지 않음	구성 파일을 저장한 후 MCP 클라이언트를 다시 시작하세요.

일반 문제

문제	해결책
도구가 나타나지 않음	클라이언트의 확장 목록에서 MCP 서버가 활성화되었는지 확인하세요.
SkipTracing이 403 반환	관리자가 팀에 대해 SkipTracing v3를 활성화해야 하며 토큰에 권한이 필요합니다.
응답 속도 저하	인터넷 연결을 확인하세요. 서버는 BatchData API에 대한 요청을 프록시합니다.

도움 받기

• API 토큰 문제: BatchData 웹 앱에 로그인하여 서버 측 토큰 관리
• 권한 문제: BatchData 팀 관리자에게 문의
• 기술 문제: BatchData 지원 팀에 문의

---

© BatchData 2025