kosis-mcp

# Tool List ## ✨ Main Features | Function | Description | |------|------| | **Intent-based Search** | Describe research purpose in natural language, and related KOSIS statistics will be automatically searched | | **One-step Retrieval** | If table name and period are clear, search and data retrieval can be done in a single call | | **Data Retrieval** | Retrieve statistical table data and deliver it to Claude | | **Claude Visualization** | Claude generates charts directly (various forms such as line, bar, pie) | | **Multi-dashboard** | Multiple statistical tables can be retrieved and visualized in a dashboard | | **Category Exploration** | Directly explore KOSIS categories by theme, target, or issue | | **Multi-user Support** | One server can be used by multiple users, each with their own KOSIS key | | **Automatic Source Display** | All output (text, table, chart) will have the statistical table name and KOSIS URL automatically attached | ## 🚀 Usage (3 steps) ### Step 1 — Obtain KOSIS Authentication Key 1. Go to [kosis.kr/openapi](https://kosis.kr/openapi/) and register 2. Click on **Application for Use → Authentication Key Issuance** (issued immediately) 3. Copy the issued authentication key ### Step 2 — Connect to Claude Claude app → **Settings** → **Connectors** → **Add Custom Connector** Enter a name freely, and enter the URL (including authentication key) in the URL field and add it: ``` https://kosis-mcp-production.up.railway.app/mcp?kosis_key=issued_authentication_key ``` > **Server Homepage**: https://kosis-mcp-production.up.railway.app > The homepage will automatically generate a connection URL when you enter the authentication key. > 💡 **Direct connection is possible even on company intranet PCs.** > In some company SSL inspection environments, Node.js (TypeScript) based MCP may fail to connect due to CA bundle issues. > This server uses Python + Railway deployment, allowing direct connection via the client's (Claude app) OS trust store and Railway's public certificate (Let's Encrypt). ### Step 3 — Talk to Claude After connection, request Claude in natural language: ``` I'm writing a report on youth policy, can you find and analyze related KOSIS statistics? ``` ``` I'm preparing a policy for low-income single-parent households, can you show me related statistical charts? ``` ``` I'm writing a paper on population decline, can you create a graph of total fertility rate and aging rate trends? ``` ``` Can you show me a line graph of youth unemployment rates over the past 10 years? ``` You don't need to know exact statistical terms - you can use everyday language like: ``` Can you find data on why people don't have kids? ``` ``` Is there a statistic that shows how much housing prices have risen? ``` ``` Can you show me data on Korea's economic growth slowdown? ``` ``` Can you find statistics on the increase in single-person households? ``` ## 💬 What Can Be Created ### 📊 Interactive Dashboard (HTML) > "Create a single-person household statistics dashboard" A single HTML dashboard file will be generated, integrating multiple statistical tables, including trends in single-person household ratios (2000-2024), comparisons of scales by region, and employment rate trends. ### 📄 Statistics-based Report (HTML / Word) > "Create a report on Korea's suicide statistics from 2005-2024" A written report will be generated, including impactful headlines like "40.7 people, who did not return," 20-year trend analysis, and detailed classification by gender and age, as well as regional comparisons. The report can be saved in Word (.docx) or HTML format. ### 🗺 Regional Market Analysis Report > "Analyze market saturation of pork restaurants in Daejeon Seo-gu" A report will be generated, analyzing market conditions for specific regions and industries using KOSIS business statistics, including trends in the number of businesses, birth rates, and closure rates. ### Other Usage Examples | Request | Output Format | |------|-----------| | "Find related statistics on youth employment and housing" | List of related statistical tables + KOSIS links | | "Create a line graph of total fertility rate from 2000" | Interactive chart | | "Compare bar charts of aging rates by region" | Chart + numerical summary | | "Collect statistics for a low birth rate policy report" | Multi-statistical table dashboard | ## 🗂 Supported Research and Policy Areas Natural language queries with the following keywords will automatically search for related statistics. **By Target**: youth · children · adolescents · elderly · elderly people · women · people with disabilities · multicultural · single-parent households **By Issue**: low birth rate · low birth rates · aging · population decline · single-person households · isolation · low income · poverty **By Subject**: employment · unemployment · education · housing · housing prices · income · wages · welfare · pension · health · medical care · population · manufacturing · mining · industry · agriculture · trade · import · export · prices · energy · national accounts (GDP · GNI · growth rate) · environment · construction · franchise · small business owners **Regional Statistics**: regional statistics by region · e-local indicators **By Institution**: National Data Portal · Ministry of Land, Infrastructure and Transport · Ministry of Health and Welfare · Ministry of Education · Ministry of Employment and Labor, etc. > 💡 **You don't need to know exact statistical terms.** Expressions like "housing prices," "not having kids," "economic growth slowdown," and "single-person households" will also be recognized. ## ⚙️ MCP Tool List | Tool | Description | |------|------| | `kosis_find_by_intent` | Natural language intent → automatic search for related statistical tables + direct KOSIS link | | `kosis_browse` | Direct exploration of KOSIS category tree (recommended for specific statistical surveys) | | `kosis_analyze` | Retrieve statistical data and deliver it to Claude (Claude generates charts) | | `kosis_dashboard` | Retrieve multiple statistics at once (Claude visualizes as a dashboard) | | `kosis_combine` | Combine multiple table data by year and calculate ratios | | `kosis_explain` | Retrieve statistical table survey purpose, cycle, and scope | ### Tool Selection Criteria | User Request | Selected Tool | Reason | |-------------|-----------|------| | "What statistics are available for low birth rates?" | `kosis_find_by_intent` | topic-based → automatic search | | "What about the mining and manufacturing survey?" | `kosis_browse` (L_5) | specific survey name → direct category exploration | | "Service industry survey sales for 5 years" | `kosis_browse` (O_8) → `kosis_analyze` | survey name + data retrieval | | "Youth employment and housing dashboard" | `kosis_find_by_intent` → `kosis_dashboard` | multi-table integration | | "What kind of survey is this?" | `kosis_explain` | metadata retrieval | ## 🔀 Overall Processing Flow ```mermaid flowchart TD A["👤 User natural language query"] --> B["🤖 Claude AI\nintent analysis"] B --> C{Query Type} C -->|"topic-based\nintent"| E["kosis_find_by_intent\nintent-based search"] C -->|"specific statistical survey\nname"| F["kosis_browse\ncategory direct exploration"] E --> G{Result Utilization} F --> G G -->|"single table analysis"| H["kosis_analyze\nbreakdown=True"] G -->|"multi-table integration"| I["kosis_dashboard\nmulti-table retrieval"] G -->|"combining multiple tables\nratio calculation"| J["kosis_combine\ntable JOIN + ratio calculation"] H -->|"metadata needed"| K["kosis_explain\nstatistical table explanation retrieval"] H --> V["🤖 Claude analysis and visualization"] I --> V J --> V K --> V V --> Z["📈 chart / report / dashboard\nsource: National Data Portal KOSIS automatically attached"] ``` ## 🔧 Key Improvement History Continuous improvements have been made to address issues found during practical use. ### Automatic Table Structure Detection Previously, table dimension structures (objL parameters) had to be manually identified for each table. The `_probe_table_params` function now automatically detects the number of dimensions and data cycles (annual/monthly/quarterly) before calling the table. → Any statistical table can be retrieved without additional settings. ### Automatic Data Cycle Detection Some tables do not have clear annual (Y), monthly (M), or quarterly (Q) cycles. → Automatic attempts are made in the order of Y → M → Q to find the correct cycle. ### Handling 40,000-cell Limit The KOSIS OpenAPI returns a maximum of **40,000 cells** per request. The number of cells = number of dimension values × number of periods, so exceeding this limit occurs with tables having many dimensions. → If exceeded (err 31), the retrieval period is automatically shortened by half up to 3 retries. → When retrieving basic data, only the "total" code for each dimension is used to minimize the number of cells. → The `breakdown=True` option allows for detailed classification by gender and age (note: increased cell count). > ⚠️ **Retrieval limit notice**: Tables with many dimensions (e.g., 104 items for cause of death × gender × 5-year age intervals) may not be fully retrieved due to the 40,000-cell limit. > In such cases, use `filter_keyword` to extract specific items or use `breakdown=False` (default) to retrieve aggregate data. ### Automatic Regional Name Conflict Resolution Administrative districts with the same name (e.g., "Seo-gu," "Jung-gu," "Nam-gu") exist nationwide, which can lead to mismatches. → Automatic AND decomposition when entering whitespace-inclusive `filter_keyword` Example) `"Daejeon Seo-gu"` → Daejeon AND Seo-gu → only Daejeon Metropolitan City Seo-gu is extracted. ### Automatic Source Display All retrieval results include the statistical table name and direct KOSIS link. | Output Format | Source Display Method | |-----------|----------------| | text · summary · analysis | source: National Data Portal KOSIS 「table name」 + URL at the bottom of the response | | table | citation + KOSIS URL at the bottom of the table | | chart · dashboard | citation displayed in chart footer (URL omitted) | ### Response Payload Lightweighting Token consumption between Claude and MCP server has been minimized based on actual measurements. | Improvement Item | Change Content | Effect | |-----------|-----------|------| | JSON compact output | `indent=2` → `separators=(',',':')` | response size ~40% reduction | | Removal of `UNIT_NM` row-by-row | repeated inclusion in each row → single `unit` field return | data array ~15% reduction | | `recent_n` default value reduction | 20 → 10 | default data halved | | `kosis_analyze` data cap | 100 rows → 60 rows | data array 40% reduction | | `kosis_dashboard` sample | 5-row sample → 25-row data | prevention of additional `kosis_analyze` calls by Claude | ### Intent Mapping Improvement — Error Correction and Expansion Incorrect category mappings found during actual use have been corrected, and supported areas have been expanded. **Error correction**: | Error Case | Cause | Correction | |-------------|------|------| | "Manufacturing statistics" → population statistics | 2-letter tokens like "move" and "death" triggered population intent | removal of 2-letter general tokens, replacement with compound words | | "National pension recipients" → undetected | missing related keywords | addition of "National Pension" and "Basic Pension" to welfare intent | | "GDP growth rate" → undetected | uppercase "GDP" keyword mismatch with lowercase query | conversion of English keywords to lowercase + case-insensitive comparison | **New intent addition**: manufacturing · industry · agriculture · trade · prices · energy · national accounts (GDP/GNI) · environment · construction (9 items) ### Enhancement of Everyday Language and Ambiguous Query Response Users often use everyday language instead of exact statistical terms. Actual usage patterns were analyzed to address the following cases. | Everyday Language Query | Recognized Intent | |-------------|------------| | "Reasons for not having kids" | low birth rate | | "Statistics showing housing prices have risen too much" | housing · housing prices | | "How serious is Korea's economic growth slowdown?" | national accounts | | "Analysis of increasing single-person households" | single-person households | | "Statistics on elderly living alone" | single-person households | | "Low birth rate data" | low birth rate | | "Economic downturn statistics" | national accounts | Whitespace-inclusive strings ("economic growth," "single-person households") are registered as keywords to support substring matching beyond word boundaries. 2-letter tokens are matched accurately on a word-by-word basis to prevent compound word mismatches. ### Automatic Korean Particle Removal 35 Korean particles (e.g., , , , , ) are automatically recognized and removed from search tokens. → Normal operation of keyword matching in everyday language expressions like "children," "housing prices," and "manufacturing" ### Automatic Merging of Separated Time Series KOSIS changes statistical compilation methods, maintaining existing tables and creating new ones. Example) Service industry survey: "10th industry classification revision (2020~)" and "11th service industry survey (2023~)" are separated as sibling categories. → `kosis_browse` automatically detects `(YYYY~)` pattern sibling categories and marks `methodology_split: true` → `kosis_analyze` merges previous method tables using `extra_tbl_ids` parameter → `coverage` field (actual time series range) and `merged_tables` field (merged table list) included in response → priority application of main table (`tbl_id`) data for overlapping years ### Direct Category Exploration — `kosis_browse` `kosis_find_by_intent` has a low hit rate for specific survey names (e.g., mining and manufacturing survey, service industry survey). → Direct category code specification is recommended. **Main category codes (MT_ZTITLE)**: | Code | Survey | |------|-----------| | `L_5` | Mining and Manufacturing Survey (number of businesses, number of employees, shipments) | | `O_8` | Service Industry Survey (retail, accommodation, food and beverage, service industry sales) | | `I` | Industry and business | | `Q` | National Accounts and Business | | `A` | Population and Household / `C` Labor and Wages / `F` Health and Medical Care | Navigate to the end of the tree, select tables with **"Summary" or "Key Indicators"** in their names, and if classification revisions have split tables, use `kosis_analyze` with `extra_tbl_ids` to merge previous tables and construct continuous time series. ### Internal Logic Improvement Pure code quality and accuracy improvements have been made, enhancing stability without changing user-exposed features. - **`filter_keyword` pre-filtering bug fix**: internal data preprocessing order issues corrected — now apply filtering to original data first - **Duplicate removal O(n²) → O(1) improvement**: changed list linear search to hash set - **Regular expression module-level move**: moved regular expressions to module constants - **Institution name conversion**: conversion of KOSIS data from "Statistics Korea" to "National Data Portal" (reflecting 2025 institution name change) - **Table identifier non-exposure**: internal identifiers like `tbl_id` and `org_id` not exposed, only statistical names provided ## 🏗 Project Structure``` kosis-mcp/ ├── server.py # MCP server (Streamable HTTP, 6 tools: find_by_intent, browse, analyze, dashboard, combine, explain) ├── kosis_client.py # KOSIS OpenAPI client library