onbid-mcp

한국어 README

LLMが온비드 (KAMCO)の韓国公売(공매)不動産データを照会できるようにするMCPサーバーです。

Claude Desktopで**「강남구で3回以上流札された物件を教えて」**と尋ねると、自分で収集したデータから回答が得られます。サブスクリプションもスクレイピングも不要です。

ステータス。 エンドツーエンドで動作中 — パイプラインはスケジュールで実行され、4つのツールはClaude Desktopでライブデータ(ソウル6,902件のリスティング、99.9%ジオコーディング済み)に対して接続・応答しています。残り: 最終受け入れチェック(M7)と、スケジュールされたバッチの1週間の監視です。正確な状態はdocs/TASKS.mdを参照してください。

提供されるもの

stdio経由で4つのツールと4つのリソース:

すべてのレスポンスにはmeta(ソース、synced_at、is_realtime: false、件数、truncated、通知)とquery_echo(デフォルト値とクランプ適用後の実際のフィルタ)が含まれます。

Related MCP server: BDLedger MCP Server

始める前に

このサーバーはホスト型サービスではなく自分のデータベースを照会します。データは自分で収集するため、自分の認証情報が必要です:

また: Python 3.11+ と Claude Desktop(またはstdio対応のMCPクライアント)。

デフォルトのスコープはソウル、売却型リスティングです。拡大は1行のフィルタ変更で可能ですが、以下のジオコーディングとクォータの数値はソウルを前提としています。

セットアップ

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行全体でKakao呼び出しは約800回で済みます。

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": "..."
      }
    }
  }
}

ここでつまずきやすい4つのポイント:

• 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

データの鮮度を保つ

2つのGitHub Actionsワークフローが含まれています。ONBID_SERVICE_KEY、SUPABASE_DATABASE_URL、KAKAO_REST_API_KEYをリポジトリのシークレットに追加すれば、自動で実行されます:

CronはUTCのみのため、04:00 KSTは前日の19:00 UTCとなり、曜日が1つずれます。先週分を確認するには:

python scripts/batch_health.py

スキップされたcronはどこにも痕跡を残しません — GitHubは開始して失敗した実行についてのみメールするため — 代わりに日数を数えます。

知っておくべき設計メモ

これらはAPIガイドではなく測定から得られたものです。

終了リスティングはマークされ、削除されません。 온비드는進行中のアイテムのみを返すため、消えたリスティングは存在しなかったものと区別できません。代わりに行は종료추정になり、その前に3つの条件がすべて満たされている必要があります: フルスキャンモード、収集スコープの一致、完了したスキャン。スコープを誤ると、測定試験で6,594行の正常な行が反転しました。

主キーは複合です。 cltrMngNoだけでは一意ではありません — 1つの管理番号に最大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をログに記録するため、クライアントはインポート時にhttpxロガーをWARNINGに下げます — そうしないとログを有効にした時点でキーが漏れます。設定オブジェクトは同じ理由でreprで値をマスクします。

すべてのonbid_*テーブルはRLSが有効でポリシーなし、権限も取り消されています。アクセスはservice_roleのみで、測定により検証済みです(すべてのテーブルでanonはHTTP 401)。HTTP APIはループバック以外へのバインドを拒否します。

制限と非目標

• 参照のみ。 ランキング、スコアリング、レコメンデーションはありません — ツールは公開データを返し、判断はあなたに委ねます。これは意図的です: 공인중개사법は物件のリスティング形式の表示と広告を制限しています。

• 仲介、評価、法的・投資アドバイスはありません。

• デフォルトはソウル、売却型リスティング、進行中のみ。

• 落札統計は偏ったサンプルに基づきます(上記参照)。

ライセンス

未定。온비드 APIガイドのドキュメントは意図的にこのリポジトリから除外されています。ここで使用されるレスポンス構造は、ライブ測定からdocs/API_FINDINGS.mdに記録されています。