内容
# electionmcp
韩国第9届全国同时地方选举（2026年6月3日）候选人信息自然语言查询·比较
中央选举管理委员会官方数据整理后提供的 **MCP(Model Context Protocol) 服务器**.
```
" 성동구청장 후보 알려줘 "
" 경기도 도지사 후보들 학력이랑 경력 비교해줘 "
" 서울특별시 시도지사 후보 중 사퇴한 사람 누구야? "
```
原始数据 → Parquet → DuckDB 内存查询 → MCP 工具 → AI 客户端.
所有回应均**注明来源（中央选举管理委员会）**, 并在系统层面屏蔽评价、推荐或偏颇解读.
| | |
|---|---|
| 直播端点 | `https://mcp.electionmcp.kr/mcp` |
| 健康检查 | `https://mcp.electionmcp.kr/health` |
| 数据集 | [skylee993393/korea-local-election-2026](https://huggingface.co/datasets/skylee993393/korea-local-election-2026) |
| 许可证 | MIT（代码）· 公共누리 1类型（数据） |
---
## 项目宗旨
地方选举1次投票中，选民需要同时选择4~7名代表（市·道长，区·市·郡长，广域议员，基础议员，教育感）。
候选人信息由中央选举管理委员会公开，但分散在多个网站和PDF中，难以一目了然地比较和验证。
`electionmcp` 将分散的官方数据规范化为单一数据集，并通过自然语言接口
使选民能够在充分审议自己选区候选人的基础上进行投票。
法律依据：**公职选举法第49条** —— 通过候选人信息公开保障国民的知情权和选举权。
---
## 数据可用性（时间线）
根据选举日程，NEC公开的信息种类会阶段性扩展。本服务的可用数据也会相应变动。
### 阶段矩阵
| 阶段 | 时间 | 候选人基本信息 | 施政纲领 | 信息公开资料PDF | 号码 |
|---|---|:---:|:---:|:---:|:---:|
| **预备候选人（市·道/市·长）** | 2/20 ~ 5/13 | ✓ | ✗ | ✗ | ✗ |
| **预备候选人（郡议员/郡长）** | 3/22 ~ 5/13 | ✓ | ✗ | ✗ | ✗ |
| **正式注册申请** | 5/14 09:00 ~ 5/15 18:00 | (转换) | (转换) | (转换) | (赋予) |
| **选举期间** | 5/16 ~ 6/2 | ✓ | ✓ (市·道长·区市郡长·教育感) | ✓ (前科·财产·兵役·纳税·学历·经历) | ✓ |
| **选举日** | 6/3 | ✓ | ✓ | ✓ (截至当日) | ✓ |
| **选举后** | 6/4 ~ | ✓ (快照保存) | ✓ (快照保存) | ✗ (NEC屏蔽) | ✓ |
### 阶段注意事项
- **5/14~15 正式注册时**：预备候选人数据立即从NEC API中删除，并替换为正式候选人数据。
本服务将在5/15 23:00重新执行完整扫描以更新数据集。
- **5/16起**：信息公开资料PDF针对每个候选人激活。本服务将在5/16 02:00执行PDF收集+
文本提取（pdfplumber → PaddleOCR fallback）。
- **5/28起**：根据公职选举法§108，禁止进行民意调查结果公布。本服务不受影响，
因为它不提供民意调查或支持率信息。
- **6/3后**：NEC将信息公开资料PDF转为非公开。本服务在6/3 23:59前收集的快照
将永久保存在HuggingFace Dataset中，并继续以相同数据回应。
---
## 当前可用数据（截至2026-04-29）
### 候选人索引：9,215名（预备候选人）
| 选举种类 | 候选人数量 |
|---|---:|
| 市·道长 | 92 |
| 区·市·郡长 | 1,335 |
| 市·道议员（地区） | 2,245 |
| 区·市·郡议员（地区） | 5,458 |
| 教育感 | 85 |
| 广域·基础议员比例代表 | 0（正式注册日由政党统一提交） |
### 注册状态分布
| 状态 | 人数 |
|---|---:|
| 注册（活动） | 8,324 |
| 辞职 | 689 |
| 注册无效 | 201 |
| 死亡 | 1 |
### 每个候选人提供的字段
```
hubo_id 候选人唯一ID
name 姓名（汉字）
hanja_name 姓名（韩文）
gender 性别
birthday 生日
age 年龄
addr 地址
party 政党（jdName）
sido 广域市·道
sgg 市·郡·区
district 选区
sg_type / name 选举种类代码 / 名称
job 职业
edu 学历（1行总结）
career1, 2, 3 经历（各1行）
status 注册状态
regdate 注册日期
stage preliminary | official
```
### 目前未提供（正式注册后阶段性追加）
| 数据 | 追加时机 |
|---|---|
| 施政纲领（5大·10大） | 5/16正式注册后（仅限市·道长·区市郡长·教育感） |
| 信息公开资料 — 前科记录 | 5/16正式注册后 |
| 信息公开资料 — 财产申报 | 同上 |
| 信息公开资料 — 兵役事项 | 同上 |
| 信息公开资料 — 纳税·欠税 | 同上 |
| 信息公开资料 — 学历证明 | 同上 |
| 号码（ballot_number） | 正式注册时赋予 |
---
## 安装
本服务通过 **Streamable HTTP** 传输（MCP 规格 2025-03-26）运行。
无需单独安装软件包或本地运行。客户端直接通过HTTPS连接。
### Claude Code（CLI）
最简单的方法 — 通过一行命令注册：
```bash
claude mcp add --transport http electionmcp https://mcp.electionmcp.kr/mcp
```
注册确认：
```bash
claude mcp list
```
### Claude Desktop（macOS / Windows）
在设置文件中添加以下块：
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"electionmcp": {
"type": "http",
"url": "https://mcp.electionmcp.kr/mcp"
}
}
}
```
保存后重启Claude Desktop。
### Cursor
`设置 → Cursor 设置 → MCP → 添加新的MCP服务器`：
```json
{
"electionmcp": {
"url": "https://mcp.electionmcp.kr/mcp"
}
}
```
### Cline（VS Code 扩展）
`Cline 设置 → MCP 服务器 → 添加远程服务器`：
```
名称：electionmcp
网址：https://mcp.electionmcp.kr/mcp
类型：streamable-http
```
### 连接验证
安装后，客户端可以查询以下内容以验证功能：
```
"通过electionmcp查询首尔市长候选人"
"江南区区长候选人是谁"
```
如果响应中返回候选人列表并注明来源，则表示正常。
服务器健康检查也可以通过浏览器进行：
```
https://mcp.electionmcp.kr/health
→ {"status":"ok","candidates":9215,...}
```
---
## 提供工具
| 工具 | 说明 | 主要参数 |
|---|---|---|
| `search_candidates` | 按地区、区、政党、姓名、选举种类搜索候选人 | `sido`, `sgg`, `party`, `name`, `sg_type`, `limit` |
| `list_by_district` | 按选举种类分组列出特定选区的候选人 | `sido`, `sgg` |
| `get_candidate_detail` | 获取某位候选人的全部信息（包括施政纲领和信息公开资料） | `hubo_id` |
| `compare_candidates` | 按相同项目比较多个候选人 | `hubo_ids[]` |
| `list_districts` | 列出市或特定市的区列表 | `sido` |
| `get_dataset_info` | 数据集元信息（来源、更新时间、候选人总数） | （无） |
---
## 数据来源
| 来源 | 类型 | 许可证 |
|---|---|---|
| 公共数据门户OpenAPI — 候选人信息 | 人事信息·学历·经历 | 公共누리 1类型 |
| 公共数据门户OpenAPI — 选举纲领信息 | 施政纲领（5/16~） | 公共누리 1类型 |
| 公共数据门户OpenAPI — 代码信息 | 选举ID·市·道·区代码 | 公共누리 1类型 |
| info.nec.go.kr — 候选人信息公开资料 | 前科·财产·兵役·纳税·学历（5/16~6/3） | 公职选举法§49公开 |
---
## 透明机制
| 保证 | 内容 |
|---|---|
| 代码公开 | 本仓库中100%验证数据加工逻辑 |
| 数据集公开 | HuggingFace上可下载完整加工后数据 |
| 来源显示 | 所有响应中附带NEC原始标识符 |
| 评价屏蔽 | 通过MCP服务器指令在系统层面屏蔽推荐或优劣评价 |
| 变更历史 | 通过git + HF提交日志验证数据变更时间点 |
---
## 自主托管
```bash
git clone https://github.com/skymoonlee/electionmcp
cd electionmcp
cp env.example .env
# .env: NEC_API_KEY (data.go.kr), HF_TOKEN, HF_DATASET_REPO 输入
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
# 数据收集（4阶段流水线，可按阶段恢复）
python -m pipeline.ingest stage 1 # 候选人索引
python -m pipeline.ingest stage 2 # 施政纲领（5/16后生效）
python -m pipeline.ingest stage 3 # 信息公开PDF（5/16后生效）
python -m pipeline.ingest stage 4 # Parquet导出
# 上传到HuggingFace
python -m pipeline.upload
# MCP服务器（端口8780）
python -m mcp_server.server
```
Docker:
```bash
docker compose up -d mcp
docker compose --profile manual run --rm ingest
```
NEC OpenAPI认证密钥通过[公共数据门户](https://www.data.go.kr)会员注册后自动审批即可立即颁发（免费）。
---
## 限制与免责
- 本服务是**信息提供工具**，而非投票指南或推荐。候选人选择责任完全由选民承担。
- 通过AI的回应基于NEC原始数据，但在自然语言生成过程中可能会出现表达上的不准确。
在重要决策前，建议以[info.nec.go.kr](https://info.nec.go.kr)原文重新确认。
- 6月3日后，NEC将信息公开资料转为非公开，本服务的信息公开资料回应也将在同一时间点转为
**快照模式**。
- 本仓库假设用于符合公职选举法§49的立法目的（保障国民的知情权和选举权）。
---
## 贡献
欢迎提出问题和拉取请求。数据更正请求必须在NEC原始数据修正后方可反映。
> *本项目的唯一目的是保障选民的知情权和选举权。*
> *(公职选举法第49条)*
