KOSIS MCP

Estadísticas oficiales de KOSIS, ahora sin necesidad de entrar al sitio. Pregúntale a tu asistente de IA en coreano y obtendrás las cifras oficiales del Servicio Nacional de Datos con su fuente de inmediato.

Servidor MCP basado en la API abierta de KOSIS del Servicio Nacional de Datos (Python FastMCP). Se puede usar con Claude Desktop, Cursor, etc. mediante stdio o HTTP.

Pruébalo en 30 segundos

Escribe esto en el chat (después de registrar el conector en Claude.ai — consulta instalación abajo)

나: 광진구 고용률 알려줘

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

No necesitas entrar al sitio de KOSIS para buscar tablas estadísticas, seleccionar códigos de clasificación ni desplazarte por filas de distritos autónomos. Solo lanza el nombre del distrito autónomo y lo que quieras saber en coreano.

Related MCP server: Korea Stats MCP

Cómo cambia el trabajo de los funcionarios públicos

Las estadísticas del Servicio Nacional de Datos están todas en KOSIS. El problema es el costo de extraerlas. Si no sabes el ID de la tabla estadística, te pierdes en la búsqueda; incluso cuando la encuentras, tienes que ensamblar códigos de clasificación, ítems y periodicidad, y a nivel de distrito autónomo tienes que rebuscar entre filas dentro de la tabla. Por eso, justo antes de cada plazo de entrega de informes, terminas forcejeando con KOSIS.

Esta herramienta reduce ese proceso a una sola línea en lenguaje natural. Veámoslo en escenarios laborales reales.

📋 Discursos de política municipal, mensajes de Año Nuevo, informes de gestión — de 30 minutos a 5 segundos

Situación — Necesitas incluir un párrafo sobre "la situación actual de nuestra ciudad" en el borrador del discurso de Año Nuevo del alcalde. Copiar cifras de población, tasa de fertilidad, empleo y economía regional desde KOSIS te toma de 30 minutos a 1 hora cada vez.

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

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

El modo de una línea para discursos de chain_region_brief selecciona automáticamente los indicadores clave y los convierte en una sola frase. También puedes obtener un resumen completo de los 13 indicadores de una sola vez.

🏛 Preparación para respuestas en asambleas locales y auditorías administrativas — "¿No es más bajo que el distrito vecino?"

Situación — Un concejal planea preguntar: "¿No es la tasa de desempleo de nuestro distrito más alta que la del distrito vecino?" Necesitas consultar uno por uno los distritos autónomos adyacentes y crear una tabla comparativa.

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

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

chain_compare_regions crea una matriz de hasta 17 regiones × 8 indicadores de una sola vez, e incluso asigna un ranking por indicador. "Ranking de tasa de fertilidad de las 17 provincias y ciudades metropolitanas del país" también es una sola línea.

📑 Análisis de situación para informes de políticas y estudios de investigación — tendencia de 10 años de una sola vez

Situación — Informe del plan quinquenal para abordar la baja natalidad. Necesitas datos de series temporales para el capítulo de "tendencia de los últimos 10 años".

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

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

chain_policy_indicator analiza series temporales en 7 áreas de política (baja natalidad, envejecimiento, vivienda, empleo, seguridad pública, salud, economía) con grupos de 3 a 4 indicadores por área. Incluye tasa de cambio promedio, puntos máximos/mínimos y clasificación de tendencia.

🗣 Atención al ciudadano y comunicados de prensa — cifras oficiales al instante

Situación — Una llamada de un ciudadano preguntando: "¿Cómo está la contaminación por polvo fino en nuestro barrio últimamente?" O necesitas responder en 30 minutos con cifras para un comunicado de prensa.

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

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

Para cifras individuales usa quick_stats, para tendencias usa quick_trend. Todas las respuestas incluyen la fuente de la tabla estadística para que puedas citarlas directamente.

🎯 Hasta nivel de distrito autónomo y ciudad/condado — no te quedas con el promedio regional

Situación — Necesitas la tasa de empleo de "Gwangjin-gu", pero la búsqueda siempre arroja solo el promedio de "Seúl".

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

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

Consulta directamente más de 230 distritos autónomos, ciudades y condados de todo el país mediante tablas estadísticas de KOSIS a nivel de distrito autónomo. Se priorizan las tablas estadísticas estándar de KOSIS (con enrutamiento de código de distrito autónomo) que contienen los 226 distritos autónomos del país con la misma estructura, y solo se complementan con el anuario estadístico de distritos autónomos (.xlsx) para áreas no cubiertas por las tablas estándar. Nombres como Jung-gu o Nam-gu, que existen en varias ciudades, se distinguen con precisión si mencionas la ciudad metropolitana junto con el nombre, como "Busan Jung-gu".

🛡 No pongas directamente en tu informe las estadísticas que te dé ChatGPT

La IA general recuerda las cifras estadísticas según el momento de su entrenamiento. Si preguntas "población de Seúl", te responderá con seguridad un valor de hace varios años. Si esa cifra termina en un informe, discurso o material de auditoría nacional, es un problema.

Con este conector activado, la IA consulta en tiempo real la base de datos oficial de KOSIS cada vez que preguntas y muestra el ID de la tabla estadística (fuente) junto con la respuesta. No es una estimación, es una cita.

Para estadísticas que incluyen proyecciones futuras, se añade automáticamente la advertencia "esta cifra no es una medición real, sino una proyección del Servicio Nacional de Datos". Para los datos más recientes de tendencias demográficas (nacimientos, defunciones, matrimonios, divorcios), se añade automáticamente la advertencia "pueden ser valores provisionales". Esto evita el error de citar proyecciones o valores provisionales como si fueran mediciones reales confirmadas.

Qué puedes preguntar

Palabras clave estadísticas — 92 + 88 alias en lenguaje natural

No necesitas saber los términos oficiales. Abreviaturas y lenguaje coloquial como 집값 → precio de venta de viviendas, 노인 → población envejecida, 월소득 → salario mensual promedio se convierten automáticamente. También reconoce errores ortográficos como 출산률 en lugar de 출산율, espacios como G D P, y términos en inglés como population o gdp.

Los indicadores con definiciones diferentes no se reemplazan silenciosamente — para preguntas sobre estadísticas que parecen similares pero son diferentes, como 청년실업률 (tasa de desempleo juvenil, 15-29 años), 연봉 (salario anual) o 가계소득 (ingreso del hogar), en lugar de dar una respuesta incorrecta, se indica "qué estadística deberías consultar". Lo mismo ocurre con los nombres de regiones — no se devuelve un valor nacional en lugar de un nombre de región no reconocido.

Regiones — 17 provincias/ciudades metropolitanas + más de 230 distritos autónomos/ciudades/condados

Las 17 provincias y ciudades metropolitanas de todo el país (tanto nombres completos como abreviaturas) y más de 230 distritos autónomos, ciudades y condados. Expresiones de período propias de la administración coreana como "tendencia de la tasa de fertilidad de la 8ª elección popular", "GRDP del 4º año de mandato", "tasa de desempleo respecto al año pasado", "población histórica" se convierten automáticamente al número de años de análisis.

14 herramientas

La mayoría de las preguntas se resuelven con quick_stats, quick_trend, quick_rank y las 3 herramientas de cadena. El resto son para consultas de precisión.

Instalación

Método 1 — stdio local (Claude Desktop / Cursor)

Requisitos: Python 3.11+ · Clave de API abierta de KOSIS (gratuita)

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

Registro con un clic:

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

También puedes poner KOSIS_API_KEY=... en el archivo .env de la raíz del proyecto (consulta .env.example).

Método 2 — Docker Compose (despliegue en servidor)

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

• MCP: POST /mcp (por defecto :3000)

• Salud: GET /health

• Redis: red interna de compose (REDIS_URL=redis://redis:6379/0)

Método 3 — Vercel (HTTP sin servidor)

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://<tu-proyecto>.vercel.app/mcp

• Salud: GET /health

• Redis: configurar REDIS_URL tras conectar Upstash Redis (caché en memoria si no se configura)

• Conexión con Cursor:

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

Para ejecutar solo HTTP localmente:

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

Precisión y confiabilidad

• Fuente oficial — Todas las cifras se consultan en tiempo real a través de la API abierta de KOSIS del Servicio Nacional de Datos. La respuesta incluye el ID de la tabla estadística para que puedas citarla y verificarla directamente.

• Distinción de datos proyectados — Las estadísticas que incluyen proyecciones futuras llevan automáticamente la advertencia "proyección".

• Integridad de datos a nivel de distrito autónomo — Si los datos a nivel de distrito autónomo no están disponibles en KOSIS, no se responde fingiendo que el valor de la provincia/ciudad metropolitana es el valor del distrito autónomo, sino que se indica explícitamente "se ha reemplazado con datos de la provincia/ciudad metropolitana".

• Caché — Las consultas idénticas se almacenan en caché durante 6 horas para una respuesta rápida, sin comprometer el período de actualización de las estadísticas.

Historial de cambios

• Bloqueo de rutas que mostraban cifras incorrectas como si fueran correctas — Se eliminó el comportamiento de devolver silenciosamente un valor nacional para nombres de región no reconocidos (reemplazado por error + aviso de regiones compatibles), se eliminó la sustitución no autorizada de alias por indicadores con definiciones diferentes como 청년실업률 o 연봉 (convertido en mensaje informativo), se bloqueó el error de coincidencia parcial de palabras compuestas como 다문화인구 o 유소년인구 con 인구

• Cambio de ruta del índice de envejecimiento — De la tabla exclusiva de proyecciones futuras (DT_1YL12501E, años 2033-2052) a la medición real del censo de población (DT_1IN2030). La proporción de población envejecida se separó como una palabra clave independiente (índice ≠ proporción)

• Adición automática de advertencia de valor provisional para los datos más recientes de tendencias demográficas (nacimientos, defunciones, matrimonios, divorcios), inclusión del ID de la tabla estadística y la fecha de última actualización (LST_CHN_DE) en la indicación de la fuente

• 2 nuevas herramientas — quick_rank (ranking, percentil, brecha con el promedio, variación de ranking frente al total de entidades del mismo nivel), explain_statistic (definición estadística, propósito de elaboración, periodicidad de la encuesta + nota al pie para informes). 12 herramientas → 14 herramientas

• Robustez — Fusión de solicitudes in-flight con la misma clave (prevención de estampida de caché), límite de concurrencia de 8 en herramientas de cadena (prevención de 136 llamadas simultáneas a KOSIS para 17×8), introducción de pruebas unitarias con vitest

• v1.8.1 — Sustitución de la explicación estadística por el endpoint oficial (statisticsExplData.do) + refuerzo de la validación de búsqueda de código de distrito autónomo

• v1.8.2 ~ v1.8.5 — Asignación de anotaciones de herramientas MCP (solo lectura, no destructivo, idempotente, openWorld), exposición de nombres de herramientas en inglés tal cual (si se añade un título no ASCII, la web de claude.ai no reconoce la lista de herramientas), reducción de descripciones de herramientas que eran demasiado extensas

• Migración del despliegue a un host unificado — Dirección oficial mcp.gomdori.app/stats (se suspende la antigua kosis-mcp.fly.dev)

• Migración completa de TypeScript/Node MCP a Python FastMCP 3.4.7

• Eliminación de la dependencia de npm / host unificado gomdori — stdio independiente + Streamable HTTP

• Análisis de Excel: de kordoc a openpyxl conversión a Markdown

• Mantenimiento de 14 herramientas, 2 recursos y 1 prompt

Licencia

MIT

Proyectos de referencia

• Dayoooun/kosis-mcp — Punto de inicio de la bifurcación de este proyecto. Agradecemos profundamente al original. La licencia es la misma MIT que el original.

• FastMCP — Framework de servidor MCP en Python.