KOSIS MCP

KOSIS der Nationalen Datenbehörde, jetzt ohne die Website zu besuchen. Wenn Sie den KI-Assistenten auf Koreanisch fragen, werden die offiziellen Zahlen der Nationalen Datenbehörde sofort mit Quellenangabe ausgegeben.

MCP-Server basierend auf der KOSIS OpenAPI der Nationalen Datenbehörde (Python FastMCP). Verwendung über stdio oder HTTP in Claude Desktop, Cursor usw.

In 30 Sekunden ausprobieren

Geben Sie dies in den Chat ein (nach Registrierung des Claude.ai Connectors — siehe Installation unten 참고)

나: 광진구 고용률 알려줘

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

Sie müssen nicht die KOSIS-Website besuchen, um Statistiktabellen zu suchen → Klassifikationscodes auszuwählen → durch die Zeilen der autonomen Bezirke zu scrollen. Sie müssen nur den Namen des autonomen Bezirks und Ihre Frage auf Koreanisch eingeben.

Related MCP server: Korea Stats MCP

So ändert sich die Arbeit von Beamten

Die Statistiken der Nationalen Datenbehörde sind alle auf KOSIS. Das Problem sind die Kosten für den Abruf. Ohne die Statistiktabellen-ID irrt man in der Suche umher, selbst wenn man sie findet, muss man Klassifikations-, Item- und Periodencodes zusammensetzen, und für die autonomen Bezirke muss man in der Tabelle nach Zeilen suchen. Deshalb kämpft man vor jeder Berichtsabgabefrist mit KOSIS.

Dieses Tool reduziert diesen Prozess auf eine einzige Zeile in natürlicher Sprache. Sehen wir es in realen Arbeitsszenarien.

📋 Stadtratsrede, Neujahrsansprache, Arbeitsbericht — 30 Minuten werden zu 5 Sekunden

Situation — In den Entwurf der Neujahrsansprache des Bürgermeisters muss ein Absatz über 'den aktuellen Stand unserer Stadt' eingefügt werden. Das Abschreiben von Bevölkerungs-, Geburten-, Beschäftigungs- und Regionalwirtschaftszahlen aus KOSIS dauert jedes Mal 30 Minuten bis 1 Stunde.

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

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

Der Einzeilenmodus für Reden von chain_region_brief filtert automatisch die Kernindikatoren heraus und fasst sie in einem Satz zusammen. Auch ein vollständiges Briefing aller 13 Indikatoren ist auf einmal möglich.

🏛 Vorbereitung auf Antworten im Kommunalparlament und Verwaltungsprüfungen — 'Ist das nicht niedriger als in der Nachbargemeinde?'

Situation — Ein Abgeordneter wird fragen: 'Ist die Arbeitslosenquote in unserem Bezirk nicht höher als in den Nachbarbezirken?' Sie müssen die benachbarten autonomen Bezirke einzeln abfragen und eine Vergleichstabelle erstellen.

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

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

chain_compare_regions erstellt bis zu 17 Regionen × 8 Indikatoren auf einmal als Matrix und ordnet sie nach Indikator. Auch 'Rangfolge der Geburtenrate in 17 Provinzen landesweit' ist eine Zeile.

📑 Analyse von Politikberichten und Forschungsaufträgen — 10-Jahres-Trend auf einmal

Situation — Bericht zum 5-Jahres-Plan zur Bekämpfung der niedrigen Geburtenrate. Es werden Zeitreihendaten für das Kapitel 'Trend der letzten 10 Jahre' benötigt.

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

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

chain_policy_indicator analysiert 7 Politikbereiche (niedrige Geburtenrate, Alterung, Wohnen, Arbeitsplätze, öffentliche Sicherheit, Gesundheit, Wirtschaft) in Zeitreihen mit 3-4 Indikatoren pro Bereich. Die durchschnittliche Änderungsrate, Höchst-/Tiefstwerte und Trendklassifizierung werden mitgeliefert.

🗣 Bürgeranfragen und Pressemitteilungen — Offizielle Zahlen auf Anfrage sofort

Situation — Ein Bürgeranruf: 'Wie ist die Feinstaubbelastung in unserer Gegend in letzter Zeit?' Oder Sie müssen innerhalb von 30 Minuten Zahlen für eine Pressemitteilung liefern.

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

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

Einzelne Werte mit quick_stats, Trends mit quick_trend. Alle Antworten enthalten die Quellenangabe der Statistiktabellen und können direkt zitiert werden.

🎯 Bis zur Ebene der autonomen Bezirke, Kreise und Städte — nicht in den Durchschnittswerten der Metropolregionen untergehen

Situation — Sie benötigen die Beschäftigungsquote für 'Gwangjin-gu', aber die Suche liefert immer nur den Durchschnitt für 'Seoul'.

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

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

Es werden landesweit über 230 autonome Bezirke, Kreise und Städte direkt über die KOSIS-Statistiktabellen auf Bezirksebene abgefragt. Dabei werden vorrangig die KOSIS-Standardtabellen (mit Bezirkscode-Routing) verwendet, die alle 226 Kreise und Bezirke landesweit in einheitlicher Struktur enthalten. Nur für Bereiche, die nicht in den Standardtabellen enthalten sind, wird auf das statistische Jahrbuch der Bezirke (.xlsx) zurückgegriffen. Namen wie Jung-gu oder Nam-gu, die in mehreren Städten vorkommen, werden genau unterschieden, wenn die Metropolregion mit angegeben wird, z.B. 'Busan Jung-gu'.

🛡 Verwenden Sie nicht einfach die von ChatGPT gelieferten Statistiken in Ihrem Bericht

Normale KI merkt sich statistische Werte zum Zeitpunkt des Trainings. Wenn Sie nach der 'Bevölkerung von Seoul' fragen, gibt sie selbstbewusst einen Wert von vor Jahren an. Wenn diese Zahl in Berichte, Reden oder Materialien für die parlamentarische Prüfung einfließt, ist das ein Desaster.

Wenn dieser Connector aktiviert ist, fragt die KI bei jeder Frage die offizielle KOSIS-Datenbank in Echtzeit ab und gibt die Statistiktabellen-ID (Quelle) in der Antwort an. Es ist keine Schätzung, sondern ein Zitat.

Bei Statistiken mit Bevölkerungsprognosen wird automatisch der Hinweis 'Diese Zahl ist keine tatsächliche Messung, sondern eine Prognose der Nationalen Datenbehörde' hinzugefügt. Bei aktuellen Bevölkerungsdaten (Geburten, Todesfälle, Heiraten, Scheidungen) wird der Hinweis 'Kann vorläufig sein' automatisch angehängt. Dies verhindert, dass Prognosen oder vorläufige Werte wie endgültige Messungen zitiert werden.

Was kann man fragen?

Statistik-Keywords — 92 + 88 natürliche Sprachaliase

Sie müssen die offiziellen Begriffe nicht kennen. Abkürzungen und Umgangssprache werden automatisch umgewandelt, z.B. 집값 (Hauspreis) → 주택매매가격 (Hausverkaufspreis), 노인 (Alte) → 고령인구 (ältere Bevölkerung), 월소득 (Monatseinkommen) → 월평균임금 (durchschnittlicher Monatslohn). Auch Tippfehler wie 출산률 statt 출산율, Leerzeichen wie G D P und englische Begriffe wie population, gdp werden erkannt.

Indikatoren mit unterschiedlicher Definition werden nicht stillschweigend ersetzt — bei Fragen, die ähnlich aussehen, aber andere Statistiken betreffen, wie 청년실업률 (Jugendarbeitslosenquote, 15-29 Jahre), 연봉 (Jahresgehalt), 가계소득 (Haushaltseinkommen), wird statt einer falschen Antwort ein Hinweis gegeben, 'welche Statistik Sie ansehen sollten'. Gleiches gilt für Regionsnamen — bei nicht erkannten Regionsnamen wird nicht stillschweigend der nationale Wert ausgegeben.

Regionen — 17 Provinzen/Metropolen + über 230 autonome Bezirke/Kreise/Städte

Landesweit 17 Metropolregionen/Provinzen (sowohl vollständige Namen als auch Abkürzungen) und über 230 autonome Bezirke/Kreise/Städte. Auch Zeitangaben in koreanischer Verwaltungssprache wie "민선 8기 출산율 추이" (Trend der Geburtenrate in der 8. gewählten Amtszeit), "임기 4년차 GRDP" (GRDP im 4. Amtsjahr), "작년 대비 실업률" (Arbeitslosenquote im Vergleich zum Vorjahr), "역대 인구" (Bevölkerung aller Zeiten) werden automatisch in Analysejahre umgerechnet.

14 Werkzeuge

Die meisten Fragen werden mit quick_stats, quick_trend, quick_rank und den 3 Kettentools beantwortet. Der Rest dient der detaillierten Abfrage.

Installation

Methode 1 — Lokales stdio (Claude Desktop / Cursor)

Voraussetzungen: Python 3.11+ · KOSIS OpenAPI-Schlüssel (kostenlos)

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": "발급받은_키" }
    }
  }
}

Ein-Klick-Registrierung:

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

Sie können auch KOSIS_API_KEY=... in die .env-Datei im Projektstammverzeichnis einfügen (siehe .env.example).

Methode 2 — Docker Compose (Serverbereitstellung)

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

• MCP: POST /mcp (Standard :3000)

• Health: GET /health

• Redis: internes Netzwerk von Compose (REDIS_URL=redis://redis:6379/0)

Methode 3 — Vercel (Serverloses 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: Nach Integration von Upstash Redis REDIS_URL setzen (ansonsten In-Memory-Cache)

• Cursor-Verbindung:

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

Wenn Sie nur HTTP lokal ausführen:

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

Genauigkeit und Zuverlässigkeit

• Offizielle Quelle — Alle Zahlen werden in Echtzeit über die KOSIS OpenAPI der Nationalen Datenbehörde abgefragt. Die Antwort enthält die Statistiktabellen-ID, sodass sie direkt zitiert und verifiziert werden kann.

• Unterscheidung von Prognosedaten — Bei Statistiken mit Bevölkerungsprognosen wird automatisch der Hinweis 'Prognose' hinzugefügt.

• Datenintegrität der autonomen Bezirke — Wenn keine Daten auf Bezirksebene in KOSIS vorhanden sind, wird nicht willkürlich der Wert der Metropolregion als Bezirkswert ausgegeben, sondern es wird angegeben, dass 'durch Daten der Metropolregion ersetzt wurde'.

• Cache — Gleiche Abfragen werden 6 Stunden lang zwischengespeichert, um schnell zu antworten, ohne den Aktualisierungszyklus der Statistiken zu beeinträchtigen.

Änderungshistorie

• Blockierung von Pfaden, die falsche Werte als korrekt ausgaben — Entfernung des stillschweigenden Zurückgebens von nationalen Werten bei nicht erkannten Regionsnamen (ersetzt durch Fehler + Hinweis auf unterstützte Regionen), Entfernung der unbefugten Alias-Ersetzung durch Indikatoren mit unterschiedlicher Definition wie 청년실업률 (Jugendarbeitslosenquote) und 연봉 (Jahresgehalt) (umgewandelt in Hinweistext), Behebung des Fehlers, bei dem zusammengesetzte Begriffe wie 다문화인구 (multikulturelle Bevölkerung) und 유소년인구 (Jugendbevölkerung) teilweise auf 인구 (Bevölkerung) gematcht wurden.

• Austausch des Routings für den Altersindex — Von der Tabelle für Bevölkerungsprognosen (DT_1YL12501E, 2033-2052) zur tatsächlichen Messung der Volkszählung (DT_1IN2030). Der Anteil der älteren Bevölkerung wird als separates Keyword geführt (Index ≠ Anteil).

• Automatische Anbringung des Hinweises auf vorläufige Werte bei aktuellen Bevölkerungsdaten (Geburten, Todesfälle, Heiraten, Scheidungen), Quellenangabe enthält Statistiktabellen-ID + letztes Aktualisierungsdatum (LST_CHN_DE)

• 2 neue Werkzeuge — quick_rank (Rang, Perzentil, Abweichung vom Durchschnitt, Rangänderung im Vergleich zu allen gleichrangigen Kommunen), explain_statistic (Definition der Statistik, Erstellungszweck, Erhebungszyklus + Fußnote für Berichtszitate). 12 Werkzeuge → 14 Werkzeuge

• Robustheit — Zusammenführung von In-Flight-Anfragen mit demselben Schlüssel (Verhinderung von Cache-Stampede), Gleichzeitigkeitsbegrenzung für Kettentools auf 8 (Verhinderung von 136 gleichzeitigen KOSIS-Aufrufen bei 17×8), Einführung von Vitest-Komponententests

• v1.8.1 — Austausch der Statistikbeschreibung durch den offiziellen Endpunkt (statisticsExplData.do) + verstärkte Validierung der Bezirkscode-Suche

• v1.8.2 ~ v1.8.5 — Hinzufügen von MCP-Tool-Annotationen (read-only, nicht destruktiv, idempotent, openWorld), Anzeige der Toolnamen in englischer Originalsprache (bei nicht-ASCII-Titeln erkennt die claude.ai-Weboberfläche die Tool-Liste nicht), Reduzierung der übermäßig langen Tool-Beschreibungen

• Migration der Bereitstellung zum einheitlichen Host — Offizielle Adresse mcp.gomdori.app/stats (alte Adresse kosis-mcp.fly.dev eingestellt)

• Vollständige Portierung von TypeScript/Node MCP → Python FastMCP 3.4.7

• Entfernung der Abhängigkeit von npm / gomdori einheitlichem Host — unabhängiges stdio + Streamable HTTP

• Excel-Parsing: kordoc → openpyxl Markdown-Konvertierung

• Beibehaltung von 14 Werkzeugen, 2 Ressourcen, 1 Prompt

Lizenz

MIT

Referenzierte Projekte

• Dayoooun/kosis-mcp — Ausgangspunkt des Forks dieses Projekts. Tiefer Dank an das Original. Die Lizenz ist identisch mit dem Original, MIT.

• FastMCP — Python MCP Server Framework.