Korean Stats MCP

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

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

За 30 секунд попробовать

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

나: 광진구 고용률 알려줘

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

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

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

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

Этот инструмент сокращает весь процесс до одной строки на естественном языке. Посмотрим на реальные рабочие сценарии.

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

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

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

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

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

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

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

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

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

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

📑 Политические отчёты, анализ данных для исследовательских работ — тренды за 10 лет сразу

Ситуация — отчёт по 5-летнему плану преодоления низкой рождаемости. Нужны временные ряды за последние 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. Ко всем ответам прикреплён источник (ID статистической таблицы), так что можно сразу цитировать.

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

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

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

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

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

🛡 Не помещайте в отчёт статистику, «угаданную» ChatGPT

Обычный AI запоминает статистические цифры на момент обучения. На вопрос «Население Сеула?» он с уверенностью ответит значениями многолетней давности. Если такие цифры попадут в отчёт, речь или материалы парламентской проверки — это беда.

Когда этот коннектор включён, AI при каждом запросе обращается в реальном времени к официальной базе данных KOSIS и отмечает в ответе ID статистической таблицы (источник). Это не оценка, а ссылка.

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

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

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

Не обязательно знать официальные термины. Сокращения, разговорные формы, опечатки автоматически преобразуются: цены на жильё→цены на жильё, старики→пожилое население, зарплата→среднемесячная зарплата. Распознаются ошибки в окончаниях (уровень вместо уровень), пробелы (В В П), английские слова (population, gdp).

Если показатель определён по-другому, система не подменит его молча — на запросы, похожие на разные статистики (например, молодёжная безработица (15–29 лет), годовая зарплата, доход домохозяйства), вместо неверного ответа выводится подсказка «какую статистику следует смотреть». То же с регионами — если название не распознано, не выводится значение по стране вместо запрошенного.

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

Все 17 провинций и городов национального уровня (полные и сокращённые названия) и около 230 районов/уездов. Периоды времени, принятые в корейском административном делопроизводстве, такие как «тенденция рождаемости при 8-м сроке избранных глав», «ВРП за 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/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": "발급받은_키" }
    }
  }
}

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

export KOSIS_API_KEY=발급받은_키
# PATH에 korean-stats-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)

• Health: 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

• Health: GET /health

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

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

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

Если нужно запустить только локально HTTP:

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

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

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

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

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

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

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

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

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

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

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

Лицензия

MIT

Проекты, на которые мы ссылаемся

• Dayoooun/korea-stats-mcp — отправная точка для форка этого проекта. Глубокая благодарность оригиналу. Лицензия такая же MIT.

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