Korean Stats MCP

No more visiting the KOSIS website. Ask your AI assistant in Korean, and official statistics from Statistics Korea will appear immediately with sources.

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

Try it in 30 seconds

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

나: 광진구 고용률 알려줘

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

No need to go to the KOSIS site, find a statistical table, select classification codes, or scroll through rows of autonomous districts. Just throw in the district name and what you want to know in Korean.

How public officials' work changes

All Statistics Korea data is on KOSIS. The problem is the cost of extracting it. If you don't know the table ID, you get lost in searches; even when you find it, you have to assemble classification, item, and period codes; and for autonomous districts, you have to dig through rows in the table. So every time a report deadline approaches, you wrestle with KOSIS.

This tool reduces that process to a single line of natural language. Let's see it in real work scenarios.

📋 Policy addresses, New Year's speeches, work reports — 30 minutes to 5 seconds

Scenario — You need to write a paragraph on "our city's current status" for the mayor's New Year's speech. It takes 30 minutes to 1 hour each time to manually copy population, fertility rate, employment, and local economy figures from KOSIS.

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

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

chain_region_brief's one-liner mode for speeches 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 district?"

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 each neighboring district 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 each indicator. "Ranking of fertility rates across 17 cities and provinces nationwide" is also a single line.

📑 Policy reports and research service status analysis — 10-year trends at once

Scenario — A five-year plan report on low birth rates. You need time-series data for the "recent 10-year trend" chapter.

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

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

chain_policy_indicator performs time-series analysis on 7 policy areas (low birth rate, aging, housing, jobs, public safety, health, economy) with 3–4 indicators per area. Average change rate, highest/lowest points, and trend classification are provided together.

🗣 Civil complaint responses and press releases — official figures on demand

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년 추세: 지속적인 하락 추세. ... (변화율·최고/최저점 포함)

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

🎯 Down to autonomous districts and cities/counties — not buried in metropolitan averages

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

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

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

Directly queries over 230 autonomous districts and cities/counties using KOSIS district-level statistical tables. It prioritizes KOSIS standard statistical tables (autonomous district code routing) that include all 226 cities/counties/districts nationwide in the same structure, and supplements only areas not covered by standard tables with autonomous district statistical yearbooks (.xlsx). Names like Jung-gu or Nam-gu that exist in multiple cities are accurately distinguished when you include the metropolitan city, e.g., "Busan Jung-gu."

🛡 Don't put statistics ChatGPT made up directly into your report

General AI remembers statistical figures based on its training cutoff. If you ask "Seoul population," it confidently answers with values from years ago. If those figures end up in reports, speeches, or parliamentary audit materials, it's a disaster.

With this connector enabled, the AI queries the KOSIS official database in real time every time you ask and includes the statistical table ID (source) in the response. It's not an estimate; it's a citation.

For statistics that include future projections, a notice saying "These figures are projections by Statistics Korea, not actual measurements" is automatically attached. For recent demographic trends (births, deaths, marriages, divorces), a notice saying "May be preliminary figures" is attached. This prevents mistakenly citing projections or preliminary figures as confirmed actuals.

What you can ask

Statistical keywords — 92 + over 100 natural language aliases

You don't need to know the official terms. Abbreviations and colloquial expressions like 집값 (house price) → housing sales price, 노인 (elderly) → elderly population, 월소득 (monthly income) → average monthly wage are automatically converted. Typos like 출산률 (wrong spelling of fertility rate) or 고용율 (wrong spelling of employment rate), spaces like G D P, and English terms like population or gdp are also recognized.

Indicators with different definitions are not silently swapped — for questions that seem similar but refer to different statistics, such as 청년실업률 (youth unemployment rate, ages 15–29), 연봉 (annual salary), or 가계소득 (household income), the response will guide you on "which statistic to look at" instead of giving a wrong answer. The same applies to region names — if a region name is not recognized, it will not substitute a national value.

Regions — 17 metropolitan cities/provinces + over 230 autonomous districts/cities/counties

All 17 metropolitan cities and provinces nationwide (both full names and abbreviations) and about 230 autonomous districts/cities/counties. Time expressions common in Korean administrative language, such as "민선 8기 출산율 추이" (fertility rate trend under the 8th popularly elected term), "임기 4년차 GRDP" (GRDP in the 4th year of term), "작년 대비 실업률" (unemployment rate compared to last year), and "역대 인구" (historical population), are 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 queries.

Installation

Method 1 — Local stdio (Claude Desktop / Cursor)

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

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

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

One-click registration:

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

You can also put KOSIS_API_KEY=... in the project root .env (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: internal compose 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 Upstash Redis and set REDIS_URL (in-memory cache if not set)

• Cursor connection:

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

When running only HTTP locally:

KOSIS_API_KEY=... korean-stats-mcp --http --port 3000

Accuracy and reliability

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

• Projection data distinction — For statistics that include future projections, a "projection" notice is automatically attached.

• Autonomous district data integrity — If autonomous district-level data is not available on KOSIS, it does not arbitrarily present metropolitan city/province values as if they were district values; instead, it explicitly states that "metropolitan city/province data has been substituted."

• Cache — Identical queries are cached for 6 hours for fast responses, without compromising the statistical update cycle.

Changelog

• TypeScript/Node MCP → Python FastMCP 3.4.7 full port

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

• Excel parsing: kordoc → openpyxl Markdown conversion

• Maintains 14 tools, 2 resources, 1 prompt

License

MIT

Referenced projects

• Dayoooun/korea-stats-mcp — Fork starting point of this project. Deep gratitude to the original. License is the same MIT as the original.

• FastMCP — Python MCP server framework.