KOSIS MCP

Национальное статистическое управление KOSIS, теперь не нужно заходить на сайт. Спросите AI-ассистента на корейском, и вы сразу получите официальные данные Национального статистического управления с указанием источника.

MCP-сервер на основе OpenAPI KOSIS (Python FastMCP). Используется через stdio или HTTP в Claude Desktop, Cursor и др.

Попробуйте за 30 секунд

Введите это в чат (после регистрации коннектора Claude.ai — см. инструкцию по установке ниже)

나: 광진구 고용률 알려줘

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

Не нужно заходить на сайт KOSIS, искать статистические таблицы, выбирать коды классификации и прокручивать строки муниципальных образований. Просто укажите название муниципалитета и то, что вас интересует, на корейском языке.

Related MCP server: Korea Stats MCP

Как меняется работа госслужащих

Статистика Национального статистического управления вся находится на KOSIS. Проблема в затратах на извлечение. Если вы не знаете ID таблицы, вы теряетесь в поиске; даже найдя, нужно собирать коды классификации, элементов и периодов, а для муниципальных образований — искать строки внутри таблицы. Поэтому перед каждым дедлайном отчета вы боретесь с KOSIS. Этот инструмент сокращает этот процесс до одной строки на естественном языке. Посмотрим на реальные рабочие сценарии.

📋 Речи о положении дел, новогодние обращения, отчеты о работе — 30 минут превращаются в 5 секунд

Ситуация — в черновик новогоднего обращения мэра нужно вставить абзац «Текущее состояние нашего города». Каждый раз тратится 30 минут – 1 час на копирование данных по населению, рождаемости, занятости и региональной экономике из KOSIS.

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

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

Режим одной строки для выступлений в chain_region_brief автоматически отбирает ключевые показатели и формирует одно предложение. Также можно получить полный обзор по 13 показателям за один раз.

🏛 Подготовка к ответам в местных советах и административным проверкам — «Разве у нас не ниже, чем у соседей?»

Ситуация — депутат собирается спросить: «Разве уровень безработицы в нашем районе не выше, чем в соседних?» Нужно вручную запрашивать соседние муниципалитеты и составлять сравнительную таблицу.

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

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

chain_compare_regions создает матрицу до 17 регионов × 8 показателей за один раз и ранжирует по каждому показателю. «Рейтинг рождаемости по 17 провинциям страны» — тоже одной строкой.

📑 Анализ политических отчетов и исследовательских работ — 10-летние тренды за один раз

Ситуация — отчет по пятилетнему плану борьбы с низкой рождаемостью. Нужны временные ряды для главы «Тенденции за последние 10 лет».

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

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

chain_policy_indicator выполняет временной анализ по 7 политическим областям (низкая рождаемость, старение, жилье, рабочие места, общественная безопасность, здравоохранение, экономика) с группировкой по 3–4 показателя на область. Вместе выводятся средний темп изменения, максимум/минимум и классификация тренда.

🗣 Ответы на жалобы граждан и пресс-релизы — официальные данные сразу по запросу

Ситуация — звонок с жалобой: «Как у нас в районе с мелкодисперсной пылью в последнее время?» Или нужно через 30 минут предоставить данные для пресс-релиза.

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

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

Для единичных значений — quick_stats, для трендов — quick_trend. Ко всем ответам прилагается источник таблицы, так что их можно цитировать напрямую.

🎯 До уровня муниципальных образований и уездов — не теряется в средних по региону

Ситуация — нужен уровень занятости в районе Кванджин-гу, но поиск всегда выдает среднее по Сеулу.

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

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

Запрашивает напрямую более 230 муниципальных образований и уездов по статистическим таблицам KOSIS на уровне муниципалитетов. В первую очередь используются стандартные таблицы KOSIS (маршрутизация по коду муниципалитета), в которых все 226 городов и уездов имеют одинаковую структуру, а области, отсутствующие в стандартных таблицах, дополняются статистическими ежегодниками муниципалитетов (.xlsx). Названия вроде Чун-гу или Нам-гу, встречающиеся в нескольких городах, точно различаются, если указать город вместе с регионом, например «Пусан Чун-гу».

🛡 Не вставляйте статистику, выданную ChatGPT, напрямую в отчеты

Обычный ИИ запоминает статистические данные на момент обучения. Если спросить «население Сеула», он уверенно ответит значением несколькихлетней давности. Если эти цифры попадут в отчеты, речи или материалы парламентских проверок, это будет катастрофа. При включении этого коннектора ИИ при каждом запросе в реальном времени обращается к официальной базе данных KOSIS и указывает в ответе ID таблицы (источник). Это не оценка, а цитирование.

Для статистики, включающей прогнозы, автоматически добавляется примечание «Эти данные являются прогнозом Национального статистического управления, а не фактическими измерениями», а для последних данных по демографическим тенденциям (рождаемость, смертность, браки, разводы) — «Могут быть предварительными». Это предотвращает ошибки цитирования прогнозов и предварительных данных как окончательных фактических.

Что можно спросить

Ключевые слова статистики — 92 + 88 синонимов на естественном языке

Не обязательно знать официальные термины. Автоматически преобразуются сокращения и разговорные выражения: 집값 (цена на жилье) → 주택매매가격 (цена продажи жилья), 노인 (пожилые) → 고령인구 (пожилое население), 월소득 (месячный доход) → 월평균임금 (среднемесячная зарплата). Распознаются опечатки вроде 출산률 вместо 출산율, пробелы как в G D P, а также английские слова population, gdp.

Показатели с другим определением не подменяются молча — на вопросы, похожие на 청년실업률 (уровень безработицы среди молодежи, 15–29 лет), 연봉 (годовая зарплата), 가계소득 (доход домохозяйств), которые выглядят похоже, но являются другой статистикой, вместо неверного ответа выводится подсказка «какую статистику следует смотреть». То же касается названий регионов — если регион не распознан, не выдается значение по стране вместо него.

Регионы — 17 провинций и городов + более 230 муниципальных образований и уездов

17 городов и провинций (полные и сокращенные названия) и около 230 муниципальных образований и уездов. Выражения периода в корейской административной практике, такие как "민선 8기 출산율 추이" (тенденции рождаемости в 8-й период местных выборов), "임기 4년차 GRDP" (GRDP на 4-й год срока полномочий), "작년 대비 실업률" (уровень безработицы по сравнению с прошлым годом), "역대 인구" (население за все время), автоматически преобразуются в анализируемые годы.

14 инструментов

Большинство вопросов решаются с помощью quick_stats·quick_trend·quick_rank·3 цепных инструментов. Остальные предназначены для точных запросов.

Установка

Способ 1 — Локальный stdio (Claude Desktop / Cursor)

Необходимо: Python 3.11+ · Ключ KOSIS OpenAPI (бесплатно)

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

Регистрация в один клик:

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

Также можно поместить KOSIS_API_KEY=... в .env в корне проекта (см. .env.example).

Способ 2 — Docker Compose (развертывание сервера)

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

• MCP: POST /mcp (по умолчанию :3000)

• Здоровье: GET /health

• Redis: внутренняя сеть compose (REDIS_URL=redis://redis:6379/0)

Способ 3 — Vercel (бессерверный 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

• Здоровье: GET /health

• Redis: после подключения Upstash Redis установите REDIS_URL (если не задан, используется кэш в памяти)

• Подключение Cursor:

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

При локальном запуске только HTTP:

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

Точность и надежность

• Официальный источник — все данные запрашиваются в реальном времени через OpenAPI Национального статистического управления KOSIS. В ответе указывается ID таблицы, что позволяет напрямую цитировать и проверять.

• Разграничение прогнозных данных — для статистики, включающей прогнозы, автоматически добавляется примечание «прогноз».

• Целостность данных на уровне муниципалитетов — если данные на уровне муниципалитета отсутствуют в KOSIS, не выдается значение по городу/провинции как за муниципалитет, а явно указывается, что «данные заменены на данные по городу/провинции».

• Кэш — одинаковые запросы кэшируются на 6 часов для быстрого ответа, не нарушая периодичность обновления статистики.

История изменений

• Заблокированы пути, по которым некорректные данные выдавались как правильные — удалено поведение, при котором нераспознанное название региона молча заменялось значением по стране (заменено на ошибку + список поддерживаемых регионов), устранена несанкционированная подмена синонимов для показателей с другим определением, таких как 청년실업률 (уровень безработицы среди молодежи) и 연봉 (годовая зарплата) (заменено на подсказку), исправлена ошибка частичного совпадения составных слов, таких как 다문화인구 (мультикультурное население) и 유소년인구 (детское население), с 인구 (население)

• Замена маршрутизации индекса старения — с таблицы прогнозов (DT_1YL12501E, 2033–2052 гг.) на фактические данные переписи населения (DT_1IN2030). Доля пожилого населения выделена в отдельное ключевое слово (индекс ≠ доля)

• Для последних данных по демографическим тенденциям (рождаемость, смертность, браки, разводы) автоматически добавляется примечание «могут быть предварительными», в указание источника включены ID таблицы и дата последнего обновления (LST_CHN_DE)

• 2 новых инструмента — quick_rank (ранг, процентиль, отклонение от среднего, изменение ранга по сравнению со всеми одноуровневыми муниципалитетами), explain_statistic (определение статистики, цель составления, периодичность обследования + сноска для цитирования в отчете). Инструментов 12 → 14

• Устойчивость — объединение in-flight запросов с одинаковым ключом (предотвращение stampede кэша), ограничение параллелизма цепных инструментов до 8 (предотвращение 136 одновременных вызовов KOSIS при 17×8), внедрение модульных тестов vitest

• v1.8.1 — замена объяснения статистики на официальную конечную точку (statisticsExplData.do) + усиление проверки поиска кода муниципалитета

• v1.8.2 ~ v1.8.5 — добавление аннотаций инструментов MCP (только чтение, без разрушения, идемпотентность, openWorld), имена инструментов оставлены на английском (если добавить не-ASCII заголовок, веб-интерфейс claude.ai не распознает список инструментов), сокращены излишне длинные описания инструментов

• Перенос развертывания на единый хост — официальный адрес mcp.gomdori.app/stats (прежний kosis-mcp.fly.dev прекращен)

• Полный перенос с TypeScript/Node MCP на Python FastMCP 3.4.7

• Устранена зависимость от npm / единого хоста gomdori — независимый stdio + Streamable HTTP

• Парсинг Excel: kordoc → openpyxl преобразование в Markdown

• Сохранены 14 инструментов, 2 ресурса, 1 промпт

Лицензия

MIT

Использованные проекты

• Dayoooun/kosis-mcp — точка начала форка этого проекта. Выражаем глубокую благодарность оригинальному проекту. Лицензия — MIT, как и в оригинале.

• FastMCP — фреймворк для Python MCP сервера.