Onbid Public Auction MCP

A read-only MCP that queries the official public data API of Onbid, operated by the Korea Asset Management Corporation, from Codex. It uses a BYOK (Bring Your Own Key) approach where each user enters their own public data portal service key.

It does not include bidding, login, electronic signature, deposit payment, or payment features. Search results are for candidate exploration only; before an actual bid, you must verify the original Onbid notice, attached documents, appraisal report, registration, occupancy and rights status, and the latest corrections or cancellations.

Provided Tools

• check_onbid_api_key: Check the current API key and list API access permissions

• get_onbid_codes: Guide to representative search codes

• search_onbid_properties: Search properties by region, price, area, share, number of failed auctions, etc.

• get_onbid_property: View property details, lease and registration summary, occupancy, and cautions

• search_onbid_results: Search bid results by period, including winning bid price and number of bidders

Related MCP server: Korea Real Estate MCP

1. Applying for Public Data Portal Usage

Each user must apply for the following APIs individually with their public data portal account. All are marked as free and auto-approved, but operator policies may change.

1. Next-generation Onbid real estate property list inquiry service

2. Next-generation Onbid real estate property detail inquiry service

3. Next-generation Onbid real estate bid result list inquiry service

Prepare the general authentication key issued from the public data portal My Page. Whether you enter the Encoding or Decoding key, the installation script normalizes it once.

2. Windows One-Click Installation (Recommended)

The easiest way is to download the install-onbid-mcp.bat one-click installer and double-click it. The installation wizard guides and executes the following steps in order.

• Explains the 3 required public data portal APIs and opens the application pages

• Guides you to apply with the same service key

• Secure input of the general authentication key and one-time validation of the list API

• Adds or updates the GitHub marketplace

• Checks whether the Onbid plugin is installed and active and whether the key is registered

Even if you download and run only the BAT file, it fetches the latest PowerShell installation wizard from GitHub and proceeds. The API key is not displayed on screen and is not saved in chat or files.

3. Windows PowerShell Installation

Run in PowerShell.

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

The script receives the API key as masked input, validates it with one call to the list API, and then performs the following:

• Saves the Windows user environment variable ONBID_SERVICE_KEY

• Adds the XamTE/onbid_mcp GitHub marketplace

• Installs the onbid-public-auction plugin

After installation, fully restart the Codex app. You can add -SkipValidation to skip API validation.

The installation script is provided in UTF-8 BOM format so that Korean text does not break even in existing Windows PowerShell 5.1.

Manual Installation and Other Operating Systems

First set ONBID_SERVICE_KEY as a user environment variable, then run:

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

You must restart the Codex app or terminal for the environment variable to be read. Do not put the key in command-line arguments or a Git repository.

Updates and Removal

codex plugin marketplace upgrade xamte-onbid

To remove the plugin and the API key environment variable together on Windows:

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

Add -KeepApiKey to keep the key.

API Key Handling and Privacy

Codex sends the API key from the local environment variable as a Bearer token in remote MCP requests. This server uses the key only to call the public data portal API while processing requests and does not store it in a database or logs. Response caching and request interval control separate users by SHA-256 fingerprint rather than the raw key.

General request metadata may be processed on Vercel and across the network, so see PRIVACY.md for details. This is not a structure that guarantees the key will never be exposed in public deployment, so if you need stronger control, deploy this repository yourself or run the MCP locally.

Call Volume and Performance

• The minimum interval between upstream call starts for the same user is 150ms.

• Identical requests are cached in memory for 1 minute for lists and 5 minutes for details and results.

• Concurrent identical requests are coalesced into one.

• Only network errors and 5xx are retried once; authentication and quota errors are not retried repeatedly.

• The maximum page size is 100, and the result period is up to 366 days at a time.

Operate based on the daily traffic limits shown on each API page for the public data portal development account. If multiple PCs or automation share the same key, the limits are combined. Even for personal use, it is best to avoid unnecessary repeated searches and bulk page traversal at short intervals.

Local Development

npm install
npm run check
npm run dev

When testing authenticated MCP requests locally, use the Authorization: Bearer <your service key> header. Do not put the key in .env or commits.

Deployment

The public MCP endpoint is https://onbid-mcp.vercel.app/api/mcp. No server public API key is required. If you fork and deploy your own instance, change the URL in plugins/onbid-public-auction/.mcp.json to your new /api/mcp address.

License and Responsibility

The source is distributed under the MIT license. Each user is responsible for checking the terms of use of public data and the policies of Onbid and the public data portal, and this tool does not guarantee investment returns or the legal or physical condition of properties.