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

Related MCP server: Korea Stats MCP

公务员工作，将这样改变

国家统计厅的统计数据都在 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 个 + 自然语言别名 88 个

不需要知道正式术语。 像 房价→住宅买卖价格、老人→老龄人口、月收入→月平均工资 这样的缩略语和口语会自动转换。出产率、雇佣率 等率/率的错别字，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/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

也可在项目根目录 .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（Serverless 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

准确性与可靠性

• 官方来源 — 所有数据实时查询国家统计厅 KOSIS OpenAPI。响应中标注统计表 ID，可直接引用和验证。

• 推算数据区分 — 包含未来推算的统计会自动附加“推算”提示。

• 自治区数据完整性 — 如果 KOSIS 中没有自治区级别数据，不会随意将广域市道值冒充为自治区值，而是明确说明“已用广域市道数据替代”。

• 缓存 — 相同查询缓存 6 小时以快速响应，同时不影响统计更新周期。

变更历史

• 阻断错误数据以正确答案形式输出的路径 — 移除对无法识别的地区名悄悄返回全国值的操作（替换为错误提示 + 支持地区说明），移除对 青年失业率、年薪 等 定义不同的指标 的未经授权别名替换（转为提示语），阻断 多文化人口、青少年人口 等复合词部分匹配 人口 的 bug

• 老龄化指数路由更换 — 从未来推算专用表（DT_1YL12501E，2033~2052 年）改为人口普查实测（DT_1IN2030）。老龄人口比例作为独立关键词分离（指数 ≠ 比例）

• 人口动向（出生·死亡·婚姻·离婚）最新时点自动附加 暂定值提示，来源标注包含统计表 ID + 最后更新日期（LST_CHN_DE）

• 新增 2 种工具 — quick_rank（对比同级地方政府全体排名·百分位·平均差距·排名变动）、explain_statistic（统计定义·编制目的·调查周期 + 报告引用脚注）。工具从 12 个增至 14 个

• 健壮性 — 合并相同 key 的 in-flight 请求（防止缓存 stampede），链式工具并发上限 8（防止 17×8=136 次并发 KOSIS 调用），引入 vitest 单元测试

• v1.8.1 — 将统计说明替换为正式端点（statisticsExplData.do）+ 加强自治区代码 lookup 验证

• v1.8.2 ~ v1.8.5 — 赋予 MCP 工具 annotations（只读·非破坏·幂等·openWorld），工具名保持英文原样（非 ASCII title 会导致 claude.ai 网页无法识别工具列表），缩减过大的工具 description

• 部署迁移至统一主机 — 正式地址 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 服务器框架。