onbid-mcp

한국어 README

LLM이 한국 공매 물건 데이터를 온비드 (KAMCO)에서 조회할 수 있게 해주는 MCP 서버입니다.

Claude Desktop에서 **"강남구에서 3회 이상 유찰된 물건은?"**이라고 물어보면, 직접 수집한 데이터로 답을 얻을 수 있습니다 — 구독도, 스크래핑도 없이.

상태. 엔드투엔드로 작동 중 — 파이프라인이 일정에 따라 실행되며, 네 개의 도구가 연결되어 Claude Desktop에서 실시간 데이터(서울 6,902건, 지오코딩 99.9%)로 응답하고 있습니다. 남은 작업: 최종 수용 검사(M7) 및 예약 배치 1주일 관찰. 정확한 상태는 docs/TASKS.md를 참조하세요.

제공 기능

stdio를 통해 네 개의 도구와 네 개의 리소스를 제공합니다:

모든 응답에는 meta (source, synced_at, is_realtime: false, count, truncated, notice)와 query_echo (기본값 및 클램핑 후 실제 적용된 필터)가 포함됩니다.

Related MCP server: BDLedger MCP Server

시작 전에

이 서버는 호스팅 서비스가 아닌 자체 데이터베이스를 조회합니다. 데이터를 직접 수집하므로 자체 자격 증명이 필요합니다:

또한: Python 3.11+ 및 Claude Desktop (또는 stdio를 지원하는 모든 MCP 클라이언트).

기본 범위는 서울, 매각 유형 매물입니다. 범위를 넓히는 것은 한 줄 필터 변경으로 가능하지만, 아래의 지오코딩 및 할당량 수치는 서울을 기준으로 합니다.

설정

git clone https://github.com/daehyub71/onbid-mcp.git
cd onbid-mcp
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt

cp .env.example .env          # fill in the three keys above
python scripts/migrate.py     # create tables (safe to re-run)

그런 다음 첫 데이터셋을 수집합니다. 약 2분이 걸리며 일일 API 할당량을 훨씬 밑돌아 안전합니다:

python scripts/run_batch.py

다음과 같은 출력이 보일 것입니다:

── 물건 ──
  ok · 수집 6902 · 적재 6902 · 이력 0 · tombstone 0
── 좌표 ──
  ok · 대상 500 · 좌표 500 (근사 0) · 실패 0 · 호출 133

--geocode-budget 1000 옵션으로 다시 실행하여 dataset/status가 만족스러운 지오코딩 비율을 보고할 때까지 반복하세요 — 캐시가 대부분의 호출을 흡수하므로 전체 6,902행에 약 800회의 Kakao 호출만 사용됩니다.

Claude Desktop 연결

claude_desktop_config.json에 서버를 추가하세요:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "onbid": {
      "command": "/absolute/path/to/onbid-mcp/venv/bin/python",
      "args": ["-m", "onbid_mcp.server"],
      "cwd": "/absolute/path/to/onbid-mcp",
      "env": {
        "PYTHONPATH": "/absolute/path/to/onbid-mcp",
        "SUPABASE_DATABASE_URL": "postgresql://...",
        "ONBID_SERVICE_KEY": "...",
        "KAKAO_REST_API_KEY": "..."
      }
    }
  }
}

여기서 사람들이 자주 실수하는 네 가지가 있습니다:

• PYTHONPATH가 필요합니다 — cwd만으로는 부족합니다. Claude Desktop은 cwd 항목을 적용하지 않으므로 python -m onbid_mcp.server가 패키지를 찾지 못하고 ModuleNotFoundError로 즉시 종료됩니다. 앱은 이를 "Server disconnected"로 보고하는데, 이는 경로 문제가 아닌 연결 문제처럼 보입니다.

• venv 인터프리터의 절대 경로를 사용하세요. Claude Desktop은 셸의 PATH를 상속하지 않으므로, 그냥 python을 사용하면 의존성이 전혀 없는 시스템 인터프리터를 사용하게 됩니다.

• 키는 env에 넣으세요. 앱은 프로젝트의 .env 파일을 읽지 않습니다.

• 로그는 절대 stdout으로 보내면 안 됩니다. stdout은 JSON-RPC 채널입니다. 이 서버는 바로 그 이유로 stderr로 로그를 남깁니다. print를 추가한다면 stderr로 보내세요.

Claude Desktop을 재시작한 후 다음을 시도해 보세요:

강남구에서 3회 이상 유찰된 물건 중 최저가율 60% 이하인 것 보여줘

실패하면 ~/Library/Logs/Claude/mcp-server-onbid.log를 읽어보세요 — 실제 Python 오류가 거기에 있으며, UI는 "Server disconnected"라고만 표시합니다.

Claude Desktop 없이 연결을 확인하려면:

python scripts/mcp_smoke.py        # lists tools and calls one over stdio

데이터 최신 상태 유지

두 개의 GitHub Actions 워크플로가 포함되어 있습니다. ONBID_SERVICE_KEY, SUPABASE_DATABASE_URL, KAKAO_REST_API_KEY를 저장소 시크릿에 추가하면 자동으로 실행됩니다:

Cron은 UTC만 지원하므로 04:00 KST는 전날 19:00 UTC이며, 이로 인해 요일이 하루씩 밀립니다. 지난 주를 확인하려면:

python scripts/batch_health.py

건너뛴 cron은 어디에도 흔적을 남기지 않습니다 — GitHub는 시작되어 실패한 실행에 대해서만 이메일을 보내므로, 대신 날짜를 세는 것입니다.

알아두면 좋은 설계 노트

이 내용은 API 가이드가 아닌 측정에서 얻은 것입니다.

종료된 매물은 삭제되지 않고 표시됩니다. 온비드는 진행 중인 항목만 반환하므로, 사라진 매물은 존재한 적 없는 매물과 구분할 수 없습니다. 대신 행은 종료추정으로 바뀌며, 세 가지 조건이 모두 충족되어야 합니다: 전체 스캔 모드, 수집 범위 일치, 완료된 스캔. 측정 시험에서 범위를 잘못 설정하면 6,594개의 정상 행이 뒤집혔습니다.

기본 키는 복합 키입니다. cltrMngNo 단독으로는 고유하지 않습니다 — 하나의 관리번호에 최대 10개의 pbctCdtnNo 값이 있으며, 입찰 정보 API는 각각에 대해 동일한 라운드 이력을 반환합니다. 통계는 (관리번호, 개시 시각, 라운드)로 중복을 제거합니다. 행을 세면 실제 경매 이벤트 13건이 62건처럼 보였습니다.

비율은 읽는 것이 아니라 계산됩니다. 온비드는 측정된 채움률이 0%인 비율 필드를 제공합니다. min_bid_rate는 파생되며, 정당하게 1.0을 초과할 수 있습니다(측정 최대 150.2%, 행의 9.8%에서). 따라서 클램핑되지 않습니다.

빈 결과는 오류이지 빈 목록이 아닙니다. no_result는 모델에게 필터를 완화하라고 알려줍니다. 빈 배열은 "그런 물건은 없다"고 결론 내리게 할 수 있습니다.

낙찰 통계는 편향되어 있으며, 이는 숫자보다 더 중요합니다. 보이는 완료된 경매는 낙찰 후 무산된 경우뿐입니다 — 정상적으로 완료된 매각은 목록 API에 나타나지 않습니다. 모든 응답에는 이 주의사항이 포함됩니다.

개발

ruff check .
mypy core/ onbid_mcp/ api/ tests/ scripts/
pytest -q            # 595 tests, no network
pytest -m db -q      # 361 tests against your database, inside rolled-back transactions
pytest -m live -q    # real API calls, excluded by default

데이터베이스 테스트는 항상 롤백되는 트랜잭션 내에서 실제 스키마에 대해 실행되므로 흔적을 남기지 않습니다 — 테이블 수를 전후로 비교하여 검증했습니다. 순수 테스트는 의도적으로 깨진 연결 문자열로 통과합니다.

또한 루프백에만 바인딩된 로컬 HTTP API(api/main.py)가 있어 curl로 데이터를 살펴보는 데 유용합니다. MCP 사용에는 필요하지 않습니다.

문서

사양 기반입니다. 문서가 진실의 원천이며 한국어로 작성되어 있습니다.

• docs/SPEC.md — 요구사항, 데이터 모델, MCP 도구 계약, 미해결 질문

• docs/PLAN.md — 아키텍처, 마일스톤, 테스트 전략, 위험

• docs/TASKS.md — 진행 상황 대시보드 및 문제 해결 로그

• docs/API_FINDINGS.md — 측정된 API 동작; 공식 가이드보다 우선합니다. 공식 가이드는 여러 곳에서 틀렸습니다.

보안

키는 .env(로컬) 또는 GitHub Secrets / MCP 설정 env 블록(배포)에 있으며, 코드에는 절대 포함되지 않습니다. 온비드 API는 서비스 키를 쿼리 매개변수로 요구하며 httpx는 INFO 레벨에서 전체 요청 URL을 로그로 남기므로, 클라이언트는 import 시 httpx 로거를 WARNING으로 낮춥니다 — 그렇지 않으면 로깅을 활성화할 때 키가 유출됩니다. 설정 객체는 같은 이유로 repr에서 값을 마스킹합니다.

모든 onbid_* 테이블은 정책 없이 RLS가 활성화되고 권한이 취소되어 있습니다. 접근은 service_role만 가능하며, 측정으로 검증되었습니다(모든 테이블에서 익명 사용자에게 HTTP 401). HTTP API는 루프백 외에는 바인딩을 거부합니다.

제한 사항 및 비목표

• 조회 전용. 순위, 점수, 추천 없음 — 도구는 공개 데이터를 반환하고 판단은 사용자에게 맡깁니다. 이는 의도적입니다: 공인중개사법은 매물 목록 형태의 표시 및 광고를 제한합니다.

• 중개, 평가, 법률 또는 투자 조언을 제공하지 않습니다.

• 기본적으로 서울, 매각 유형 매물, 진행 중인 항목만.

• 낙찰 통계는 편향된 표본에서 비롯됩니다(위 참조).

라이선스

아직 선택되지 않았습니다. 온비드 API 가이드 문서는 의도적으로 이 저장소에서 제외되었습니다. 여기서 사용된 응답 구조는 docs/API_FINDINGS.md에 실측 결과로 기록되어 있습니다.