Korean Stats MCP

¡Ya no necesitas entrar al sitio de KOSIS (Estadísticas Nacionales de Corea)! Pregunta en coreano a tu asistente de IA y obtén al instante las cifras oficiales de la Oficina Nacional de Estadística, con su fuente incluida.

Servidor MCP basado en la API abierta de KOSIS (Estadísticas Nacionales de Corea) (Python FastMCP). Utilizable en Claude Desktop, Cursor y otros mediante stdio o HTTP.

Pruébalo en 30 segundos

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

나: 광진구 고용률 알려줘

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

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

Así cambia el trabajo de los funcionarios públicos

Las estadísticas de la Oficina Nacional de Estadística están todas en KOSIS. El problema es el coste de extraerlas. Si no sabes el ID de la tabla estadística, te pierdes en la búsqueda; incluso si la encuentras, tienes que ensamblar los códigos de clasificación, ítem y período, y además buscar la fila del distrito autónomo dentro de la tabla. Por eso, cada vez que se acerca la fecha límite de un informe, se lucha con KOSIS.

Esta herramienta reduce ese proceso a una sola línea de lenguaje natural. Véalo en escenarios laborales reales.

📋 Discursos de política municipal, mensajes de Año Nuevo, informes de trabajo — 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 una por una las cifras de población, tasa de natalidad, empleo y economía regional desde KOSIS te lleva 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 informe completo de 13 indicadores de una sola vez.

🏛 Preparación para respuestas en asambleas locales y auditorías administrativas — "¿No es más bajo que en el municipio 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 vecinos y crear una tabla comparativa.

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

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

chain_compare_regions genera una matriz de hasta 17 regiones × 8 indicadores de una sola vez, e incluso calcula la clasificación por indicador. "Ranking de tasa de natalidad de los 17 municipios provinciales de todo el país" también es una sola línea.

📑 Informes de políticas, análisis de situación para 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 "Tendencia de los últimos 10 años".

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

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

chain_policy_indicator realiza un análisis de series temporales para 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áximo/mínimo y clasificación de tendencia.

🗣 Atención a quejas ciudadanas, comunicados de prensa — cifras oficiales al instante

Situación — Una llamada de queja: "¿Cómo está la contaminación por polvo fino en nuestro barrio últimamente?" O necesitas responder con una cifra que irá en un comunicado de prensa en 30 minutos.

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

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

Para una sola cifra usa quick_stats; para tendencias, quick_trend. Todas las respuestas incluyen la fuente de la tabla estadística, por lo que se pueden citar directamente.

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

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

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

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

Consulta directamente las tablas estadísticas de KOSIS por distrito autónomo para más de 230 distritos autónomos, ciudades y condados de todo el país. Se priorizan las tablas estadísticas estándar de KOSIS (enrutamiento por código de distrito autónomo) que contienen los 226 distritos autónomos de todo el país con la misma estructura; solo para áreas no cubiertas por las tablas estándar se complementa con los anuarios estadísticos de los distritos autónomos (.xlsx). Nombres como Jung-gu o Nam-gu que existen en varias ciudades se distinguen correctamente si se menciona la ciudad metropolitana, 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 le preguntas "población de Seúl", te responderá con seguridad el valor de hace varios años. Si esa cifra aparece en un informe, discurso o material para una 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 le preguntas y muestra el ID de la tabla estadística (fuente) junto con la respuesta. No es una estimación, es una cita.

En las 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 de la Oficina Nacional de Estadística". En los datos más recientes de tendencias demográficas (nacimientos, defunciones, matrimonios, divorcios) se añade 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 + más de 100 alias en lenguaje natural

No hace falta que sepas el término oficial. Términos abreviados o coloquiales como 집값 (precio de la vivienda) → precio de venta de viviendas, 노인 (ancianos) → población mayor, 월소득 (ingreso mensual) → salario mensual promedio se convierten automáticamente. También reconoce errores tipográficos como 출산률 (tasa de natalidad escrito incorrectamente), espacios como G D P, o palabras en inglés como population, gdp.

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

Regiones — 17 municipios provinciales + más de 230 distritos autónomos, ciudades y condados

Los 17 municipios provinciales de todo el país (tanto nombres completos como abreviaturas) y alrededor de 230 distritos autónomos, ciudades y condados. Expresiones de período típicas de la administración coreana como "Tendencia de la tasa de natalidad en la 8ª elección popular", "GRDP del cuarto año de mandato", "Tasa de desempleo respecto al año anterior", "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 en cadena. El resto son para consultas precisas.

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

Registro con un clic:

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

También puedes añadir KOSIS_API_KEY=... en el archivo .env en 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": {
    "korean-stats": {
      "url": "https://<your-project>.vercel.app/mcp",
      "headers": { "Authorization": "Bearer YOUR_MCP_AUTH_TOKEN" }
    }
  }
}

Para ejecutar solo HTTP localmente:

KOSIS_API_KEY=... korean-stats-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 (Oficina Nacional de Estadística de Corea). El ID de la tabla estadística aparece en la respuesta, por lo que se puede citar y verificar directamente.

• Distinción de datos proyectados — En las estadísticas que incluyen proyecciones futuras, se añade automáticamente la advertencia "proyección".

• Integridad de datos a nivel de distrito autónomo — Si no hay datos a nivel de distrito autónomo en KOSIS, no se responde fingiendo que el valor del municipio provincial es el del distrito autónomo, sino que se indica explícitamente "se ha sustituido por datos del municipio provincial".

• Caché — Las mismas consultas se almacenan en caché durante 6 horas para responder rápidamente, sin comprometer el período de actualización de las estadísticas.

Historial de cambios

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

• Eliminación de dependencias del host integrado npm / gomdori — stdio independiente + Streamable HTTP

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

• Se mantienen 14 herramientas, 2 recursos y 1 prompt

Licencia

MIT

Proyectos de referencia

• Dayoooun/korea-stats-mcp — Punto de inicio de este proyecto (fork). Un agradecimiento profundo al original. La licencia es la misma MIT que el original.

• FastMCP — Framework de servidor MCP en Python.