KOSIS MCP

Statistics Korea KOSIS, no need to visit the site anymore. Ask the AI assistant in Korean and official Statistics Korea figures with sources will appear immediately.

KOSIS OpenAPI-based MCP server (Python FastMCP) from Statistics Korea. Use with stdio or HTTP in Claude Desktop, Cursor, etc.

Try it in 30 seconds

Type this in the chat (after registering the connector in Claude.ai — see installation methods below)

나: 광진구 고용률 알려줘

AI: 2025년 하반기 광진구의 고용률은 61.6%입니다.
    📊 출처: 고용률 (KOSIS DT_1ES3A03_A01S)

No need to go to the KOSIS site, find a statistical table, select classification codes, and scroll through autonomous district rows. Just throw in the autonomous district name and what you're curious about in Korean.

Related MCP server: Korea Stats MCP

How Civil Servant Work Changes

Statistics Korea data is all in KOSIS. The problem is the cost of extracting it. Without knowing the statistical table ID, you get lost in searches; even after finding it, you have to assemble classification, item, and period codes; and for autonomous district units, you have to dig through rows in the table. So every time before a report deadline, you wrestle with KOSIS.

This tool reduces that process to a single line of natural language. See it in real work scenarios.

📋 Policy Address, New Year's Speech, Work Report — 30 minutes to 5 seconds

Scenario — You need to add a paragraph on "Our City Status" in the mayor's New Year's speech draft. It takes 30 minutes to 1 hour each time to copy population, fertility rate, employment, and regional economy figures one by one from KOSIS.

나: 성남시 신년사에 넣을 핵심 통계 한 줄로 정리해줘

AI: 성남시의 주민등록 인구 ○○만 명, 합계출산율 ○.○○명,
    65세 이상 고령인구 ○○만 명, 실업률 ○.○%, 지역내총생산 ○○조 원
    (○○○○년 기준)입니다.

chain_region_brief's speech-ready one-line mode automatically extracts key indicators and turns them into a single sentence. A full briefing of all 13 indicators is also possible at once.

🏛 Preparing for Local Council Responses and Administrative Audits — "Isn't it lower than the neighboring town?"

Scenario — A council member is expected to ask, "Isn't our district's unemployment rate higher than the adjacent district?" You need to manually look up adjacent autonomous districts and create a comparison table.

나: 강남구, 서초구, 송파구 실업률이랑 고용률 비교해줘

AI: 📊 3개 지역 × 2개 지표 비교
    • 실업률: 최고 ○○구(○.○%), 최저 ○○구(○.○%)
    • 고용률: 최고 ○○구(○○.○%), 최저 ○○구(○○.○%)
    [지역별 순위 매트릭스 + 기준시점 포함]

chain_compare_regions creates a matrix of up to 17 regions × 8 indicators at once and even ranks them by indicator. "Nationwide ranking of fertility rates across 17 cities and provinces" is also one line.

📑 Policy Reports, Research Service Status Analysis — 10-year trend at once

Scenario — A report on a 5-year plan for low birth rate response. You need time series data for the "Recent 10-Year Trend" chapter.

나: 저출산 영역 최근 10년 추세 정리해줘

AI: 📑 저출산 영역 10년 추세
    • 합계출산율: 지속 하락 (20○○→20○○년, -○○%)
    • 출생아수: 지속 하락 (-○○%)
    • 혼인건수: 지속 하락 (-○○%)
    • 평균초혼연령: 상승 (+○.○세)
    [연도별 데이터포인트 + 변화율 전체]

chain_policy_indicator analyzes time series for 7 policy areas (low birth rate, aging, housing, jobs, public safety, health, economy) in bundles of 3-4 indicators per area. Average change rate, highest/lowest points, and trend classification come together.

🗣 Civil Complaint Response, Press Releases — Official figures on the spot

Scenario — A phone call asking, "How's the fine dust in our neighborhood these days?" Or you need to reply with figures for a press release within 30 minutes.

나: 충남 미세먼지 수치
AI: 20○○년 충남의 PM2.5 농도는 ○○㎍/㎥입니다. 📊 출처: KOSIS

나: 부산 인구 최근 10년 변화는?
AI: 부산의 인구 10년 추세: 지속적인 하락 추세. ... (변화율·최고/최저점 포함)

For single figures, use quick_stats; for trends, quick_trend. Every response includes the statistical table source, so you can cite it directly.

🎯 Down to Autonomous Districts, Cities, Counties — Not buried in metropolitan averages

Scenario — You need the employment rate for "Gwangjin-gu," but searches always return only the average for "Seoul."

나: 광진구 고용률, 광진구 65세 이상 인구

AI: 2025년 하반기 광진구의 고용률은 61.6%입니다.
    2024년 광진구의 65세 이상 고령인구는 ○○,○○○명입니다.

It directly queries over 230 autonomous districts, cities, and counties nationwide from KOSIS autonomous district-level statistical tables. It prioritizes KOSIS standard statistical tables (autonomous district code routing) that contain all 226 cities, counties, and districts nationwide in the same structure, and supplements fields not in standard tables with autonomous district statistical yearbooks (.xlsx). For names like Jung-gu or Nam-gu that exist in multiple cities, specifying the metropolitan city together (e.g., "Busan Jung-gu") ensures accurate distinction.

🛡 Don't Put Statistics ChatGPT Guessed Directly into Your Report

General AI remembers statistical figures based on the training time. When you ask about "Seoul population," it confidently answers with values from a few years ago. If those figures go into reports, speeches, or parliamentary audit materials, it's a problem.

With this connector turned on, the AI queries the KOSIS official database in real time each time you ask and includes the statistical table ID (source) in the response. It's not estimation; it's citation.

For statistics that include future projections, a notice "This figure is a Statistics Korea projection, not actual measurement" is automatically attached. For recent demographic trends (births, deaths, marriages, divorces), a notice "May be provisional figures" is automatically attached. This prevents misquoting projections or provisional figures as confirmed actual measurements.

What You Can Ask

Statistical Keywords — 92 + 88 natural language aliases

You don't need to know the official terms. Abbreviations and colloquial expressions like house prices→housing sales price, elderly→elderly population, monthly income→average monthly wage are automatically converted. Typos like fertility rate (률/율 mix-up), spaces like G D P, and English words like population or gdp are also recognized.

Indicators with different definitions are not silently swapped — for questions that look similar but are different statistics like youth unemployment rate (ages 15–29), annual salary (yearly), or household income, the system outputs guidance on "what statistic to look at" instead of giving a wrong answer. The same applies to region names — if a region name is not recognized, it does not silently output a national value.

Regions — 17 Cities/Provinces + 230+ Autonomous Districts, Cities, Counties

All 17 metropolitan cities and provinces nationwide (both full names and abbreviations) and approximately 230 autonomous districts, cities, and counties. Period expressions in Korean administrative language such as "Fertility rate trend of the 8th popular election", "GRDP in the 4th year of term", "Unemployment rate compared to last year", "Historical population" are also automatically converted to analysis years.

14 Tools

Most questions are handled by quick_stats, quick_trend, quick_rank, and 3 chain tools. The rest are for precise lookup.

Installation

Method 1 — Local stdio (Claude Desktop / Cursor)

Prerequisites: Python 3.11+ · KOSIS OpenAPI key (free)

git clone https://github.com/chrisryugj/kosis-mcp.git
cd kosis-mcp
python3 -m venv .venv
.venv/bin/pip install -e .

{
  "mcpServers": {
    "kosis-mcp": {
      "command": "/절대경로/kosis-mcp/.venv/bin/kosis-mcp",
      "args": [],
      "env": { "KOSIS_API_KEY": "발급받은_키" }
    }
  }
}

One-click registration:

export KOSIS_API_KEY=발급받은_키
# PATH에 kosis-mcp 가 있어야 함 (.venv/bin 활성화 후)
bash install.sh --client cursor

You can also put KOSIS_API_KEY=... in the project root .env file (see .env.example).

Method 2 — Docker Compose (Server deployment)

cp .env.example .env   # KOSIS_API_KEY 설정
docker compose up -d --build

• MCP: POST /mcp (default :3000)

• Health: GET /health

• Redis: compose internal network (REDIS_URL=redis://redis:6379/0)

Method 3 — Vercel (Serverless HTTP)

cp .env.example .env   # 로컬 vercel dev용
npx vercel login
npx vercel env add KOSIS_API_KEY      # production + preview
npx vercel env add MCP_AUTH_TOKEN     # (권장) Bearer 인증
npx vercel --prod

• MCP: POST https://<your-project>.vercel.app/mcp

• Health: GET /health

• Redis: Connect with Upstash Redis and set REDIS_URL (if not set, in-memory cache will be used)

• Cursor connection:

{
  "mcpServers": {
    "kosis-mcp": {
      "url": "https://<your-project>.vercel.app/mcp",
      "headers": { "Authorization": "Bearer YOUR_MCP_AUTH_TOKEN" }
    }
  }
}

When running HTTP locally only:

KOSIS_API_KEY=... kosis-mcp --http --port 3000

Accuracy and Reliability

• Official source — All figures are queried in real time from the Statistics Korea KOSIS OpenAPI. The statistical table ID is displayed in the response, allowing direct citation and verification.

• Projection data distinction — Statistics that include future projections automatically have a "projection" notice attached.

• Autonomous district data integrity — If autonomous district-level data is not available in KOSIS, it does not pretend that metropolitan city/province values are district values; it explicitly states that "metropolitan city/province data has been substituted."

• Cache — Same queries are cached for 6 hours for fast response, but do not compromise the statistical update cycle.

Change History

• Blocked paths where incorrect figures were output as correct answers — Removed the behavior of silently returning national values for unrecognized region names (replaced with error + list of supported regions), removed unauthorized alias substitution for indicators with different definitions such as youth unemployment rate or annual salary (replaced with guidance text), blocked bugs where compound words like multicultural population or youth population partially matched population

• Aging index routing change — From the future projection-only table (DT_1YL12501E, 2033–2052) to the actual census measurement (DT_1IN2030). Elderly population ratio is separated as a separate keyword (index ≠ ratio)

• Provisional figure notice automatically attached for recent demographic trends (births, deaths, marriages, divorces), source citation includes statistical table ID and last update date (LST_CHN_DE)

• Two new tools — quick_rank (rank, percentile, average gap, rank change against all same-tier local governments), explain_statistic (statistical definition, purpose, survey period + report citation footnote). 12 tools → 14 tools

• Robustness — Merged in-flight requests for the same key (prevents cache stampede), concurrency cap of 8 for chain tools (prevents 136 simultaneous KOSIS calls for 17×8), introduced vitest unit tests

• v1.8.1 — Replaced statistical explanation endpoint with official endpoint (statisticsExplData.do) + strengthened autonomous district code lookup validation

• v1.8.2 ~ v1.8.5 — Added MCP tool annotations (read-only, non-destructive, idempotent, openWorld), exposed tool names in English as-is (non-ASCII title causes claude.ai web to not recognize the tool list), reduced overly verbose tool descriptions

• Deployment migrated to unified host — Official address mcp.gomdori.app/stats (old kosis-mcp.fly.dev discontinued)

• Full port from TypeScript/Node MCP → Python FastMCP 3.4.7

• Removed dependency on npm / gomdori unified host — independent stdio + Streamable HTTP

• Excel parsing: kordoc → openpyxl markdown conversion

• Maintained 14 tools, 2 resources, 1 prompt

License

MIT

Referenced Projects

• Dayoooun/kosis-mcp — Starting point for this fork. Deep gratitude to the original. License is the same MIT as the original.

• FastMCP — Python MCP server framework.