Onbid 公卖 MCP

这是用于在 Codex 中查询韩国资产管理公社 Onbid 官方公共数据 API 的只读 MCP。采用 BYOK(Bring Your Own Key) 方式，由每位用户直接输入自己的公共数据门户服务密钥。

不提供竞拍、登录、电子签名、保证金缴纳、支付功能。搜索结果仅用于候选探索，实际竞拍前务必亲自确认 Onbid 原文公告、附件文件、评估报告、登记、占有·权利关系以及最新更正·取消情况。

提供工具

• check_onbid_api_key: 确认当前 API 密钥及列表 API 访问权限

• get_onbid_codes: 主要搜索代码指南

• search_onbid_properties: 按地区·价格·面积·份额·流拍次数等搜索拍品

• get_onbid_property: 查询拍品详情、租赁·登记摘要·占有·注意事项

• search_onbid_results: 按期间搜索成交价·竞拍人数等竞拍结果

1. 公共数据门户使用申请

每位用户都需要使用自己的公共数据门户账户，分别对以下 API 提出使用申请。这些 API 均显示为免费·自动批准，但运营机构政策可能会发生变化。

1. 新一代 Onbid 不动产拍品列表查询服务

2. 新一代 Onbid 不动产拍品详细信息查询服务

3. 新一代 Onbid 不动产竞拍结果列表查询服务

请准备在公共数据门户“我的页面”中签发的普通认证密钥。无论输入 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 一次进行验证，然后执行以下操作。

• 保存 Windows 用户环境变量 ONBID_SERVICE_KEY

• 在 GitHub Marketplace 中添加 XamTE/onbid_mcp

• 安装 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 许可证发布。公共数据的使用条件以及 Onbid·公共数据门户的政策需由各用户自行确认；本工具不保证投资收益，也不保证拍品的法律·物理状态。