온비드 공매 MCP

한국자산관리공사 온비드의 공식 공공데이터 API를 Codex에서 조회하는 읽기 전용 MCP입니다. 각 사용자가 자신의 공공데이터포털 서비스 키를 직접 입력하는 BYOK(Bring Your Own Key) 방식입니다.

입찰, 로그인, 전자서명, 보증금 납부, 결제 기능은 없습니다. 검색 결과는 후보 탐색용이며 실제 입찰 전에는 반드시 온비드 원문 공고와 첨부서류, 감정평가서, 등기, 점유·권리관계, 최신 정정·취소 여부를 직접 확인해야 합니다.

제공 도구

• check_onbid_api_key: 현재 API 키와 목록 API 접근 권한 확인

• get_onbid_codes: 대표 검색 코드 안내

• search_onbid_properties: 지역·가격·면적·지분·유찰횟수 등 물건 검색

• get_onbid_property: 물건 상세, 임대차·등기 요약·점유·주의사항 조회

• search_onbid_results: 기간별 낙찰가·입찰자 수 등 입찰결과 검색

1. 공공데이터포털 활용신청

사용자마다 공공데이터포털 계정으로 아래 API를 각각 활용신청해야 합니다. 모두 무료·자동승인으로 표시되지만 운영기관 정책은 바뀔 수 있습니다.

1. 차세대 온비드 부동산 물건목록 조회서비스

2. 차세대 온비드 부동산 물건상세정보 조회서비스

3. 차세대 온비드 부동산 입찰결과 목록 조회서비스

공공데이터포털 마이페이지에서 발급된 일반 인증키를 준비하세요. Encoding 또는 Decoding 키 어느 쪽을 입력해도 설치 스크립트가 한 번 정규화합니다.

2. Windows 빠른 설치

PowerShell에서 실행합니다.

git clone https://github.com/XamTE/onbid_mcp.git
powershell -ExecutionPolicy Bypass -File .\onbid_mcp\scripts\install.ps1

스크립트가 API 키를 마스킹 입력으로 받고, 목록 API를 1회 호출해 검증한 뒤 다음 작업을 합니다.

• Windows 사용자 환경변수 ONBID_SERVICE_KEY 저장

• XamTE/onbid_mcp GitHub 마켓플레이스 추가

• onbid-public-auction 플러그인 설치

설치 후 Codex 앱을 완전히 다시 시작하세요. API 검증을 건너뛰려면 -SkipValidation을 추가할 수 있습니다.

수동 설치 및 다른 운영체제

먼저 ONBID_SERVICE_KEY를 사용자 환경변수로 설정한 다음 실행합니다.

codex plugin marketplace add XamTE/onbid_mcp --ref main
codex plugin add onbid-public-auction@xamte-onbid

환경변수를 읽히려면 Codex 앱이나 터미널을 다시 시작해야 합니다. 키를 명령행 인자나 Git 저장소에 넣지 마세요.

업데이트와 삭제

codex plugin marketplace upgrade xamte-onbid

Windows에서 플러그인과 API 키 환경변수를 함께 삭제하려면:

powershell -ExecutionPolicy Bypass -File .\scripts\uninstall.ps1

키를 유지하려면 -KeepApiKey를 추가합니다.

API 키 처리와 개인정보

Codex는 로컬 환경변수의 API 키를 원격 MCP 요청의 Bearer 토큰으로 보냅니다. 이 서버는 요청 처리 중에만 키를 사용해 공공데이터포털 API를 호출하며 데이터베이스나 로그에 저장하지 않습니다. 응답 캐시와 요청 간격 제어는 키 원문이 아닌 SHA-256 지문으로 사용자별 분리됩니다.

Vercel과 네트워크 구간에서 일반적인 요청 메타데이터가 처리될 수 있으므로 자세한 내용은 PRIVACY.md를 확인하세요. 공공 배포에서 키의 완전한 비노출을 보장하는 구조는 아니므로, 더 강한 통제가 필요하면 이 저장소를 직접 배포하거나 MCP를 로컬에서 운영하세요.

호출량과 성능

• 동일 사용자의 상류 호출 시작 간격을 최소 150ms로 제한합니다.

• 동일 요청은 목록 1분, 상세·결과 5분 동안 메모리 캐시합니다.

• 동시 동일 요청은 하나로 합칩니다.

• 네트워크 오류와 5xx만 한 번 재시도하며 인증·한도 오류는 반복 재시도하지 않습니다.

• 페이지 크기는 최대 100, 결과 기간은 한 번에 최대 366일입니다.

공공데이터포털 개발계정의 일일 트래픽은 각 API 페이지에 표시된 한도를 기준으로 운영하세요. 여러 PC나 자동화가 같은 키를 공유하면 한도도 합산됩니다. 개인 사용이라도 필요 없는 반복 검색과 짧은 간격의 대량 페이지 순회는 피하는 것이 좋습니다.

로컬 개발

npm install
npm run check
npm run dev

로컬에서 인증된 MCP 요청을 시험할 때는 Authorization: Bearer <본인 서비스 키> 헤더를 사용합니다. 키를 .env나 커밋에 넣지 마세요.

배포

Vercel에 배포한 뒤 plugins/onbid-public-auction/.mcp.json의 URL을 실제 /api/mcp 주소로 맞추면 됩니다. 서버 공용 API 키는 필요하지 않습니다.

라이선스와 책임

소스는 MIT 라이선스로 배포됩니다. 공공데이터의 이용조건과 온비드·공공데이터포털 정책은 각 사용자가 확인해야 하며, 이 도구는 투자수익이나 물건의 법적·물리적 상태를 보증하지 않습니다.