onbid-mcp

한국어 README

一个MCP服务器，让LLM查询来自온비드 (KAMCO)的韩国公开拍卖（공매）房产数据。

在Claude Desktop中询问**“강남구中流拍超过三次的房产有哪些？”**，然后从你自己收集的数据中获得答案——无需订阅，无需爬取。

状态。 端到端工作——管道按计划运行，四个工具已连接并在Claude Desktop中针对实时数据（6,902条首尔房源，99.9%已地理编码）进行回答。剩余：最终验收检查（M7）和一周的定时批次观察。确切状态请参阅docs/TASKS.md。

你会得到什么

四个工具和四个资源，通过stdio提供：

每个响应都带有meta（来源、synced_at、is_realtime: false、计数、截断、通知）和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)

然后收集第一个数据集。这大约需要两分钟，并且远在每日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而死亡。应用将其报告为“服务器已断开”，这看起来像是连接问题而不是路径问题。

• 使用venv解释器的绝对路径。 Claude Desktop不会继承你的shell PATH，因此裸python会使用系统解释器，且没有依赖项。

• 将密钥放在env中。 应用不会读取项目的.env文件。

• 日志绝不能到达stdout。 stdout是JSON-RPC通道；此服务器正是因此记录到stderr。如果你添加print，请将它们发送到stderr。

重启Claude Desktop，然后尝试：

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

如果失败，请阅读~/Library/Logs/Claude/mcp-server-onbid.log——实际的Python错误就在那里，而UI只显示“服务器已断开”。

要在没有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并不唯一——一个管理编号最多携带十个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可访问，已通过测量验证（每个表对匿名用户返回HTTP 401）。HTTP API拒绝绑定到除回环以外的任何地方。

限制和非目标

• 仅查询。 没有排名、评分或推荐——工具返回公共数据，判断由你来做。这是故意的：공인중개사법限制列表式展示和房产广告。

• 不提供经纪、估值、法律或投资建议。

• 默认首尔、销售型房源、进行中。

• 中标统计来自有偏差的样本（见上文）。

许可证

尚未选择。온비드 API指南文档有意排除在此仓库之外；此处使用的响应结构记录在docs/API_FINDINGS.md中，来自实时测量。