Content
# electionmcp
The **MCP(Model Context Protocol) server** provides official data from the National Election Management Committee in a structured and queryable format.
```
"Tell me about the candidates for the Seongdong-gu mayor."
"Compare the educational backgrounds and careers of Gyeonggi-do governor candidates."
"Who withdrew from the Seoul metropolitan government candidates?"
```
Raw data → Parquet → DuckDB in-memory query → MCP tool → AI client.
All responses include the **source (National Election Management Committee)**, and evaluations, recommendations, or biased interpretations are blocked at the system level.
| | |
|---|---|
| Live Endpoint | `https://mcp.electionmcp.kr/mcp` |
| Health Check | `https://mcp.electionmcp.kr/health` |
| Dataset | [skylee993393/korea-local-election-2026](https://huggingface.co/datasets/skylee993393/korea-local-election-2026) |
| License | MIT (code) · Public Domain 1 (data) |
## Project Purpose
In local elections, voters must choose 4-7 representatives (governors, mayors, councilors, and education superintendents) simultaneously.
Candidate information is publicly available from the National Election Management Committee but is scattered across multiple sites and PDFs, making it difficult to compare and verify at a glance.
`electionmcp` normalizes the scattered official data into a single dataset and provides a natural language interface for voters to review candidates in their district based on objective facts before voting.
Legal basis: **Electoral Act Article 49** — Ensuring the right to know and exercise the right to vote through candidate information disclosure.
## Data Availability (Timeline)
The types of information disclosed by the NEC change in stages according to the election schedule. The available data for this service also changes accordingly.
### Stage Matrix
| Stage | Period | Basic Candidate Info | Pledge | PDF Disclosure Documents | Ballot Number |
|---|---|:---:|:---:|:---:|:---:|
| **Preliminary Candidates (Provincial/Municipal)** | 2/20 ~ 5/13 | ✓ | ✗ | ✗ | ✗ |
| **Preliminary Candidates (County Councilors/County Heads)** | 3/22 ~ 5/13 | ✓ | ✗ | ✗ | ✗ |
| **Official Registration Application** | 5/14 09:00 ~ 5/15 18:00 | (transition) | (transition) | (transition) | (assigned) |
| **Election Period** | 5/16 ~ 6/2 | ✓ | ✓ (governors, mayors, county heads, education superintendents) | ✓ (criminal records, property, military service, tax payment, education, career) | ✓ |
| **Election Day** | 6/3 | ✓ | ✓ | ✓ (until the day) | ✓ |
| **Post-Election** | 6/4 ~ | ✓ (snapshot preserved) | ✓ (snapshot preserved) | ✗ (NEC blocked) | ✓ |
### Stage-Specific Notes
- **5/14-15 Official Registration**: Preliminary candidate data is immediately removed from the NEC API and replaced with official candidate data. This service updates the dataset by re-running a full scan with official registration data at 23:00 on 5/15.
- **From 5/16**: PDF disclosure documents are activated for each candidate. This service executes PDF collection and text extraction (pdfplumber → PaddleOCR fallback) at 02:00 on 5/16.
- **From 5/28**: The period for public disclosure of opinion poll results under the Electoral Act §108 begins. This service is not affected as it does not provide opinion polls or approval ratings.
- **After 6/3**: The NEC switches the disclosure documents to non-public. A snapshot collected by 6/3 23:59 is permanently preserved in the HuggingFace Dataset, and this service continues to respond with the same data.
## Currently Available Data (as of 2026-04-29)
### Candidate Index: 9,215 (Preliminary Candidates)
| Election Type | Number of Candidates |
|---|---:|
| Governors | 92 |
| Mayors | 1,335 |
| Provincial Councilors (constituency) | 2,245 |
| Municipal Councilors (constituency) | 5,458 |
| Education Superintendents | 85 |
| Proportional Representation | 0 (to be submitted by parties on official registration day) |
### Registration Status Distribution
| Status | Number of Candidates |
|---|---:|
| Registered (active) | 8,324 |
| Withdrawn | 689 |
| Registration Invalidated | 201 |
| Deceased | 1 |
### Fields Provided per Candidate
```
hubo_id Unique candidate ID
name Name (Korean)
hanja_name Name (Chinese characters)
gender Gender
birthday Date of birth
age Age
addr Address
party Party (jdName)
sido Metropolitan city/province
sgg City/county/district
district Election district
sg_type / name Election type code / name
job Occupation
edu Education (1-line summary)
career1, 2, 3 Career (each 1-line)
status Registration status
regdate Registration date
stage preliminary | official
```
### Currently Not Provided (to be added in stages after official registration)
| Data | Addition Time |
|---|---|
| Pledge (top 5/10) | After official registration on 5/16 (limited to governors, mayors, county heads, education superintendents) |
| Disclosure Documents — Criminal Records | After official registration on 5/16 |
| Disclosure Documents — Property Declaration | Same |
| Disclosure Documents — Military Service | Same |
| Disclosure Documents — Tax Payment/Delinquency | Same |
| Disclosure Documents — Education Verification | Same |
| Ballot Number | Assigned upon official registration |
## Installation
This service operates on **Streamable HTTP** transport (MCP specification 2025-03-26). No separate package installation or local execution is required. Clients connect directly via HTTPS.
### Claude Code (CLI)
The simplest method — register with a one-line command:
```bash
claude mcp add --transport http electionmcp https://mcp.electionmcp.kr/mcp
```
Verify registration:
```bash
claude mcp list
```
### Claude Desktop (macOS / Windows)
Add the following block to the settings file:
- 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"
}
}
}
```
Save and restart Claude Desktop.
### Cursor
`Settings → Cursor Settings → MCP → Add new MCP server`:
```json
{
"electionmcp": {
"url": "https://mcp.electionmcp.kr/mcp"
}
}
```
### Cline (VS Code extension)
`Cline settings → MCP Servers → Add Remote Server`:
```
Name : electionmcp
URL : https://mcp.electionmcp.kr/mcp
Type : streamable-http
```
### Connection Verification
After installation, verify the operation by querying from the client:
```
"Search for Seoul metropolitan government candidates using electionmcp"
"Who are the Gangnam-gu mayor candidates?"
```
If the response returns a list of candidates with the source, it is normal.
Server health check is also possible with a browser:
```
https://mcp.electionmcp.kr/health
→ {"status":"ok","candidates":9215,...}
```
## Provided Tools
| Tool | Description | Main Arguments |
|---|---|---|
| `search_candidates` | Search candidates by metropolitan city/province, city/county/district, party, name, election type | `sido`, `sgg`, `party`, `name`, `sg_type`, `limit` |
| `list_by_district` | Group all candidates in a specific election district by election type | `sido`, `sgg` |
| `get_candidate_detail` | Retrieve all information (pledges, disclosure documents) for a single candidate | `hubo_id` |
| `compare_candidates` | Compare multiple candidates based on the same criteria | `hubo_ids[]` |
| `list_districts` | List city/county/districts in a metropolitan city/province or specific metropolitan city/province | `sido` |
| `get_dataset_info` | Dataset meta-information (source, update time, total number of candidates) | (none) |
## Data Source
| Source | Type | License |
|---|---|---|
| Public Data Portal OpenAPI — Candidate Information | Personal details, education, career | Public Domain 1 |
| Public Data Portal OpenAPI — Election Pledge Information | Pledge (from 5/16) | Public Domain 1 |
| Public Data Portal OpenAPI — Code Information | Election ID, metropolitan city/province, city/county/district code | Public Domain 1 |
| info.nec.go.kr — Candidate Disclosure Documents | Criminal records, property, military service, tax payment, education (from 5/16 to 6/3) | Electoral Act §49 disclosure |
## Transparency Mechanism
| Guarantee | Content |
|---|---|
| Code Disclosure | 100% verification of data processing logic possible in this repository |
| Dataset Disclosure | Entire processed dataset available for download on HuggingFace |
| Source Indication | Original NEC identifier attached to all responses |
| Evaluation Blocking | Recommendation and superiority evaluation blocked at the MCP server level |
| Change History | Data change points verifiable with git + HF commit log |
## Self-Hosting
```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 input
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
# Data collection (4-stage pipeline, resumable by stage)
python -m pipeline.ingest stage 1 # Candidate index
python -m pipeline.ingest stage 2 # Pledge (valid from 5/16)
python -m pipeline.ingest stage 3 # Disclosure PDF (valid from 5/16)
python -m pipeline.ingest stage 4 # Parquet export
# HuggingFace upload
python -m pipeline.upload
# MCP server (port 8780)
python -m mcp_server.server
```
Docker:
```bash
docker compose up -d mcp
docker compose --profile manual run --rm ingest
```
NEC OpenAPI authentication key can be issued immediately after automatic approval (free) by registering as a member on [Public Data Portal](https://www.data.go.kr).
## Limitations and Disclaimers
- This service is an **information provision tool**, not a voting guide or recommendation. The responsibility for choosing candidates lies entirely with the voters.
- AI responses are based on the original NEC data but may have inaccuracies in expression during natural language generation.
It is recommended to recheck with the original text on [info.nec.go.kr](https://info.nec.go.kr) before making important decisions.
- After June 3rd, the NEC switches disclosure documents to non-public, and this service's disclosure document responses also switch to *snapshot mode*.
- This repository is used under the assumption that it complies with the legislative purpose of the Electoral Act §49 (ensuring the right to know and exercise the right to vote).
## Contribution
Issues and pull requests are welcome. Data correction requests must be made to the NEC original data first.
> *The sole purpose of this project is to ensure the right to know and exercise the right to vote.*
> *(Electoral Act Article 49)*
