korea-public-data-catalog-mcp

# Korea Public Data Catalog MCP  > Public remote server version: `v0.4.0-beta.1` · Default runtime mode: `catalog` “This is a read-only MCP server that helps you find related data names, providers, formats, and official links from the static list of 96,056 public data entries on the Korea Public Data Portal. It also suggests candidate data to review together. The server is provided with a public HTTPS server for Claude Custom Connector and a local server for direct execution. This project is a **metadata router**, not a **data executor**. It does not call public APIs or download files when you ask questions, and it does not provide actual data values or real-time information. ## How it Works ```text Service idea you want to create ↓ Search related data types from 96,056 static public data entries ↓ Suggest data name, provider, format, and official link combinations ↓ User verifies current status, usage conditions, and actual schema on the official page ``` The above figure is a generative image created to illustrate this flow. It is not an actual government system screen, official authentication, or real-time query result. For image asset guidelines and precautions, see [Image Asset Guide](docs/IMAGE-ASSET.md). ## Current Catalog Scope | Item | Current Value | |---|---:| | Source | Korea Public Data Portal `Public Data Portal List Status` | | Source snapshot date | 2026-06-30 | | Unique list strictly parsed from CSV | **96,056 entries** | | Total rows displayed on source detail page | **87,581 entries** | | Difference between the two values | **8,475 entries** | | Network/API calls during queries | None | The 96,056 entries are verified using a strict CSV parser from the official CSV, with unique `(list type, list key)` pairs. The [source detail page](https://www.data.go.kr/data/15062804/fileData.do) shows 87,581 rows. This project does not hide or arbitrarily discard the 8,475-entry difference and publicly provides both values. **Neither value claims to represent the total national public data volume of Korea.** For differences in aggregation timing or portal aggregation criteria, refer to the source. The list types for 96,056 entries are: `FILE` (83,695), `API` (12,061), and `STD` (300). These are catalog entry counts, not actual file rows or API call counts. Each entry includes the minimum fields required for routing: - List key and list type - Data name, provider, and classification system - Provided format, update cycle, and search keywords - Official `data.go.kr` URL and usage permission text from the source Raw data rows, file contents, API responses, detailed descriptions, contact information for administrators, and authentication keys are not included. ## Getting Started with Claude ### Recommended: Public Remote Custom Connector No installation or Node.js required. Open the link below in your browser after logging in to Claude, confirm the displayed name and address, and click **Add** or **추가**. [Add Korea Public Data Catalog to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Korea+Public+Data+Catalog&connectorUrl=https%3A%2F%2Fkorea-public-data-catalog-mcp-production.up.railway.app%2Fmcp) When entering manually, use the following values in `Settings/Customize → Connectors → Add custom connector`. The screen name may vary slightly depending on the Claude version. ```text Name: Korea Public Data Catalog Remote MCP URL: https://korea-public-data-catalog-mcp-production.up.railway.app/mcp Authentication: None ``` Make sure to include `/mcp`. GitHub address, server root address, `/health`, and `localhost` are not Connector URLs. To recreate the pre-filled link from the repository, use the following command: ```powershell npm run claude:install-link -- https://korea-public-data-catalog-mcp-production.up.railway.app/mcp ``` If you encounter an HTTP `429` error, retry after the `Retry-After` time specified in the response. Requests sharing the same network exit can use the same per-minute rate limit. After connecting, enable the **Korea Public Data Catalog** tool in the new chat's Connectors menu and run the [first test](#first-test-after-connection). ### Local Alternative 1: Installing `.mcpb` for Claude Desktop Release For those who want to run the tool on their own PC without using the public server. 1. Download `korea-public-data-catalog-mcp-v0.3.0-beta.2.mcpb` from the [v0.3.0-beta.2 release](https://github.com/obundh/korea-public-data-catalog-mcp/releases/tag/v0.3.0-beta.2). 2. Double-click the file or drag it to Claude Desktop. Alternatively, select it from `Settings → Extensions → Advanced settings → Install Extension…`. 3. After installation, select the **Korea Public Data Catalog** tool from the `+ → Connectors` menu in a new chat. This file is a beta version for Windows and macOS, packaged without a digital signature, so you may encounter installation warnings. You can compare the hash of the downloaded file with the [SHA-256 file](https://github.com/obundh/korea-public-data-catalog-mcp/releases/download/v0.3.0-beta.2/korea-public-data-catalog-mcp-v0.3.0-beta.2.mcpb.sha256) provided in the release. GitHub-hosted Desktop Extensions do not update automatically. When a new release is available, download and manually install the new `.mcpb` file. For versions without a `.mcpb` file, use Claude Code or [manual Desktop setup](docs/CLAUDE-SETUP.md). ### Local Alternative 2: Using `.mcp.json` in Claude Code Requires Node.js 22.16 or higher, Git, and Claude Code. The repository already includes a scoped `.mcp.json`, so you don't need to register the absolute path. ```powershell git clone https://github.com/obundh/korea-public-data-catalog-mcp.git cd korea-public-data-catalog-mcp npm ci npm run build npm test claude ``` When you first open it, trust the repository (workspace) and approve the use of the project MCP. Inside Claude Code, run `/mcp` to verify that **korea-public-data-catalog** and 7 tools are visible. This setup only applies when running Claude Code from this repository. If you want to use the same server across all projects, you can register it separately at the user level. Replace the path with the actual repository absolute path: ```powershell claude mcp add --transport stdio --scope user korea-public-data-catalog -- node "E:\absolute\path\korea-public-data-catalog-mcp\dist\index.js" claude mcp list claude mcp get korea-public-data-catalog ``` The public remote Connector uses the public server, so no installation or local updates are required. `.mcpb`, `.mcp.json`, and manual JSON setup are local methods to run the same 7 tools on your PC. Both methods search a static snapshot of 96,056 entries and do not call real-time public APIs. For installation, manual setup, and troubleshooting, refer to [Claude Connection Guide](docs/CLAUDE-SETUP.md). ## First Test After Connection First, check the scope: > Tell me how many metadata entries are currently searchable. Distinguish between the count parsed from CSV and the count reported by the source page, and do not claim either represents the total public data volume of Korea. Also, do not call external APIs. If successful, it should explain 96,056 entries, 87,581 entries, a difference of 8,475 entries, a reference date of 2026-06-30, and `network_access: false` using `get_inventory_coverage_status`. Next, describe something you want to create: > I want to create a service to compare neighborhoods in Seoul that are good for raising children. Find public data candidates related to kindergartens, schools, parks, hospitals, air quality, and housing, and provide their providers and official links. Suggest which data to review together and any missing items. Do not retrieve actual values or verify combinations. Alternatively, you can ask: > I'm planning a dashboard for flood response in Busan. Find candidates for flood history, rainfall, drainage facilities, shelters, and population-related data, and propose a combination order. Note that different regions, times, and code systems may apply, and indicate items to verify from the raw data. The response suggests data candidates and official verification paths. Since it does not query actual rows or verify schema and combination keys, distinguish between unmet requirements and uncertainties in your reading. ### Example Response The actual text will vary depending on how Claude organizes it, but a normal response includes the following structure: ```text Recommendation status: Reference metadata candidates - Kindergartens: candidate data name / provider / format / official data.go.kr link - Schools: candidate data name / provider / format / official data.go.kr link - Parks: candidate data name / provider / format / official data.go.kr link - Hospitals, air quality, housing prices: similar candidates and missing requirements Pre-combination verification: - Actual addresses, administrative dong codes, and reference dates - Current provision status and authentication methods - Usage conditions, third-party rights, and personal information - Actual fields and combination keys Caution: No actual values or real-time APIs were queried, and combination success is not guaranteed. ``` Eight examples, including responses for electric vehicle charging stations, Busan flood response, and requests for the latest values, are provided in [Copy-Paste Prompts and Response Examples](docs/PROMPT-EXAMPLES.md). ## 7 Public Tools | Tool | Function | |---|---| | `get_inventory_coverage_status` | Verify snapshot date, two entry counts, and differences, and catalog scope | | `list_public_data_sources` | Confirm included sources and update criteria | | `search_public_datasets` | Search candidates by topic, region, institution, and format | | `get_public_dataset_details` | Verify minimal metadata and official URL for a candidate | | `recommend_data_combination` | Suggest candidate bundles and unmet requirements for a goal | | `design_public_data_product` | Design product configuration and verification sequence based on candidates | | `check_combination_feasibility` | Check metadata-based combination feasibility for selected candidates | No execution tools like `call_api` are provided. ## Update Method The server does not scrape the portal every time you ask. It searches a monthly static snapshot included in the repository, providing high speed and reproducibility without requiring API keys. However, it does not automatically reflect new data registered on the portal or content changes. For public remote Connector users, there is no need to update or reinstall for each query. When the project administrator deploys a verified new snapshot to the server, it applies to subsequent requests. Desktop Extension users must manually reinstall a new `.mcpb` file, and source users must update the repository, rebuild, and restart Claude. Regardless of the method, always verify the current status, latestness, usage conditions, and download/API methods from the official URL before using actual raw data. ## Reference Results and Legal Boundaries - The MIT License of the project code does not grant rights to linked public data or provider documents. - Metadata usage permission texts are exploratory information from the source and do not constitute legal opinions, approvals, or risk-free guarantees. - Recommendations do not guarantee the accuracy, completeness, latestness, or purpose suitability of specific data or combination success. - This does not imply official service, recommendation, certification, or partnership from the government, Korea Public Data Portal, or data providers. - Before acquiring, processing, combining, commercially using, or redistributing actual files/APIs, directly verify the current conditions, third-party rights, and inclusion of personal information from the official pages. - Do not automate critical decisions (e.g., disaster, medical, welfare) solely based on this routing result. For detailed principles, see [Legal Safety Design](LEGAL-SAFETY.md), [Privacy Guide](PRIVACY.md), and [Notice](NOTICE.md). These documents are not legal advice. ## Development Verification ```powershell npm run check npm test npm run inventory:check npm run inventory:test:legal-compliance npm pack --dry-run --json --ignore-scripts ``` To visually inspect the MCP protocol and tool list locally: ```powershell npm run inspect ``` Automated tests verify the MCP protocol and tool responses. Since the actual connection varies by user environment, verify the connection with the above verification commands and test prompts. ### Desktop Extension Maintenance Release managers create verified `.mcpb` and SHA-256 files using a dedicated staging procedure. ```powershell npm run desktop:pack ``` The result using `desktop-extension/manifest.json` as a template is generated in `artifacts/`. Do not run `mcpb pack` on the entire repository root or compress the entire repository into an extension bundle. The dedicated script stages the public runtime, static catalog, necessary documents, and production dependencies, ensuring that internal inventory, raw materials, tests, and development files are not mixed into the bundle. ## Documentation and Reporting - [Beginner's Guide](docs/BEGINNER-GUIDE.md) - [Claude Connection Guide](docs/CLAUDE-SETUP.md) - [Remote Deployment and Operation Guide](docs/REMOTE-DEPLOYMENT.md) - [Copy-Paste Prompts and Response Examples](docs/PROMPT-EXAMPLES.md) - [Generative Image Asset Guide](docs/IMAGE-ASSET.md) - [Legal Safety Design](LEGAL-SAFETY.md) - [Privacy Guide](PRIVACY.md) - [Correction and Blocking Requests](TAKEDOWN.md) - [Security and Sensitive Information Reporting](SECURITY.md) - [Notice](NOTICE.md) General errors and public metadata corrections can be suggested via GitHub Issues. For secret values, personal information, and security vulnerabilities, use GitHub's private vulnerability reporting instead of publicly writing the original text.