Korean Stats MCP

国家数据处 KOSIS，现在无需进入网站。 用韩语向AI助手提问，国家数据处的官方数据会连同来源立即显示。

基于国家数据处 KOSIS OpenAPI 的 MCP 服务器（Python FastMCP）。可在 Claude Desktop、Cursor 等环境中通过 stdio 或 HTTP 使用。

30秒体验

在聊天窗口中输入以下内容（注册 Claude.ai 连接器后 — 参见下方安装方法）

나: 광진구 고용률 알려줘

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

无需进入 KOSIS 网站查找统计表 → 选择分类代码 → 滚动查找自治区的行。 只需用韩语输入自治区名称和你想了解的内容即可。

公务员工作，将这样改变

国家数据处的统计数据都在 KOSIS 上。问题在于提取使用的成本。 不知道统计表 ID 就会在搜索中迷失，找到后还要组装分类、项目、周期代码，自治区单位还需要在表中逐行查找。因此每次报告截止前都要与 KOSIS 搏斗。

这个工具将这个过程简化为一行自然语言。让我们看看实际工作场景。

📋 施政演说·新年贺词·工作报告 — 30分钟变成5秒

场景 — 市长新年贺词稿中需要加入“我市现状”一段。从 KOSIS 逐一复制人口、出生率、就业、地区经济数据，每次需要30分钟到1小时。

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

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 自治区单位统计表直接查询。优先使用收录全国226个市郡区相同结构的 KOSIS 标准统计表（自治区代码路由），标准表未覆盖的领域才用自治区统计年报（.xlsx）补充。像中区、南区这样多个城市都有的名称，只要同时说出广域市如“釜山中区”即可准确区分。

🛡 ChatGPT 给出的统计数据，不要直接放入报告

普通 AI 根据学习时间点记忆统计数据。问“首尔人口”时，它会自信地回答几年前的数值。如果该数值进入报告、演说稿、国政监察资料，就会出问题。

开启此连接器后，AI 每次提问时实时查询 KOSIS 官方数据库，并在回答中标注统计表 ID（来源）。不是推测，而是引用。

包含未来推算的统计会自动附加“该数据为国家数据处推算，非实测”的提示；人口动向（出生、死亡、婚姻、离婚）最近时点会附加“可能为暂定值”的提示。防止将推算、暂定值当作确定实测引用。

可以问什么

统计关键词 — 92个 + 自然语言别名100个以上

不知道正式术语也没关系。 房价→住宅买卖价格、老人→高龄人口、月收入→月平均工资等缩略语、口语会自动转换。출산률·고용율等率/率错别字、G D P等空格、population·gdp等英文也能识别。

定义不同的指标不会悄悄替换 — 对于青年失业率（15~29岁）·年薪（年单位）·家庭收入等看似相似但实际不同的统计问题，不会给出错误答案，而是提示“应该查看哪个统计”。地区名也一样 — 无法识别的地区名不会用全国值代替。

地区 — 17个市道 + 自治区·市郡230个以上

全国广域市道17个（全称、简称均可）和自治区、市郡230余处。“民选8期出生率趋势”、“任期4年GRDP”、“同比失业率”、“历年人口”等韩国行政用语中的期间表达也会自动换算为分析年数。

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

也可在项目根目录 .env 中放入 KOSIS_API_KEY=...（参见 .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": {
    "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 服务器框架。