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
라이선스	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

후보자 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 transport(MCP 사양 2025-03-26)로 운영된다. 별도 패키지 설치·로컬 실행 불필요. 클라이언트가 HTTPS로 직접 연결한다.

Claude Code (CLI)

가장 간단한 방법 — 한 줄 명령어로 등록:

claude mcp add --transport http electionmcp https://mcp.electionmcp.kr/mcp

등록 확인:

claude mcp list

Claude Desktop (macOS / Windows)

설정 파일에 다음 블록 추가:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "electionmcp": {
      "type": "http",
      "url": "https://mcp.electionmcp.kr/mcp"
    }
  }
}

저장 후 Claude Desktop 재시작.

Cursor

Settings → Cursor Settings → MCP → Add new MCP server:

{
  "electionmcp": {
    "url": "https://mcp.electionmcp.kr/mcp"
  }
}

Cline (VS Code 확장)

Cline 설정 → MCP Servers → Add Remote Server:

Name : electionmcp
URL  : https://mcp.electionmcp.kr/mcp
Type : 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	후보자 1인의 전체 정보(공약·정보공개자료 포함)	hubo_id
compare_candidates	후보자 N인을 동일 항목 기준으로 정렬 비교	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 서버 instruction 으로 추천·우열 평가 시스템 차원 차단
변경 이력	git + HF 커밋 로그로 데이터 변경 시점 검증 가능

---

자체 호스팅

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단계 파이프라인, 단계별 resume 가능)
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 export

# HuggingFace 업로드
python -m pipeline.upload

# MCP 서버 (port 8780)
python -m mcp_server.server

Docker:

docker compose up -d mcp
docker compose --profile manual run --rm ingest

NEC OpenAPI 인증키는 공공데이터포털 회원가입 후 자동승인으로 즉시 발급(무료).

---

한계 및 면책

• 본 서비스는 정보 제공 도구이며 투표 안내·추천이 아니다. 후보 선택의 책임은 전적으로 유권자에게 있다.
• AI를 통한 응답은 NEC 원본 데이터에 기반하지만 자연어 생성 과정에서 표현상 부정확이 발생할 수 있다. 중요 의사결정 전 info.nec.go.kr 원문으로 재확인을 권한다.
• 6월 3일 이후 NEC가 정보공개자료를 비공개 전환하므로, 본 서비스의 정보공개자료 응답도 같은 시점에 스냅샷 모드로 전환된다.
• 본 저장소는 공직선거법 §49의 입법 목적(국민의 알권리·선거권 행사 보장)에 부합하는 사용을 전제로 한다.

---

기여

이슈 및 풀 리퀘스트 환영. 데이터 정정 요청은 NEC 원본이 먼저 수정되어야 반영 가능.

본 프로젝트의 유일한 목적은 유권자의 알권리와 선거권 행사 보장이다. (공직선거법 제49조)