kr-elections-mcp

South Korean Election MCP (kr-elections-mcp)

Korean README

    

South Korean Election MCP (kr-elections-mcp) is a local Python FastMCP server for South Korean election research. It combines NEC open data, normalized result adapters, and krpoltext text lookups into task-oriented MCP tools.

This repository is composite-first. It does not mirror every raw NEC endpoint as a public MCP tool. Instead, it focuses on higher-value workflows such as candidate packets, district summaries, election overviews, diagnostics, and safe text lookups.

What It Provides

• Candidate search and profile retrieval
• Candidate policy retrieval when NEC coverage is available
• District-level election results and summaries
• Party vote-share history and election overviews
• krpoltext text lookup for campaign booklet corpus rows
• Composite packet assembly across NEC, results, and krpoltext text
• NEC API diagnostics for local BYOK usage

Quick Start

1. Install the CLI

Requires Python 3.11+.

Recommended for most users:

pipx install .

pipx keeps the CLI isolated and makes it easier to point MCP clients at a stable kr-elections-mcp command.

If you prefer plain pip:

python -m pip install .

For development from a repository checkout:

python -m venv .venv
# activate the virtual environment for your shell
python -m pip install -r requirements.txt
python -m pip install -e .

This project is currently distributed as a Python package, not an npm package. If your MCP client is JavaScript- or Node-based, install the Python CLI first and then reference kr-elections-mcp from the client config below.

2. Apply for NEC API access

This project uses a BYOK model. Each user must apply for the relevant NEC OpenAPI products through the Public Data Portal (data.go.kr).

The Public Data Portal notes that encoded and decoded service keys can behave differently depending on API environment or invocation conditions. This server accepts both forms.

See:

• API Access Guide
• Source Status

3. Store the key securely

Recommended:

kr-elections-mcp setup-key

setup-key accepts both encoded and decoded NEC service keys. You can store one or both.

Important behavior:

• If only NEC_API_KEY_DECODED is present, the server derives the encoded variant automatically.
• Request order is always decoded first, then encoded.
• Legacy NEC_API_KEY still works as a fallback.

Useful commands:

kr-elections-mcp show-key-source
kr-elections-mcp clear-key

4. Run the MCP server

kr-elections-mcp run

MCP Client Example

After installation, your MCP client should launch the Python-installed CLI, not an npm wrapper.

{
  "mcpServers": {
    "south-korean-election": {
      "command": "kr-elections-mcp",
      "args": ["run"]
    }
  }
}

If you do not want OS keyring storage, you can provide the key in the MCP client environment instead:

{
  "mcpServers": {
    "south-korean-election": {
      "command": "kr-elections-mcp",
      "args": ["run"],
      "env": {
        "NEC_API_KEY_DECODED": "YOUR_DECODED_KEY"
      }
    }
  }
}

NEC_API_KEY_ENCODED is not required if the decoded key is already available.

API Key Storage Rules

Key lookup priority is:

1. Process environment or MCP client env
2. OS keyring
3. .env development fallback

Within each source, the server prefers NEC_API_KEY_DECODED and NEC_API_KEY_ENCODED, then falls back to legacy NEC_API_KEY.

Recommended for public users:

• Use kr-elections-mcp setup-key when possible.
• Keep keys out of chat, screenshots, and Git commits.
• Treat .env as a development-only fallback.
• If you intentionally use .env, pass it explicitly with --env-file .env.
• In many environments, NEC_API_KEY_DECODED alone is enough.

Source Checkout Fallback

If you are running directly from a repository checkout instead of an installed package, the legacy commands still work:

python server.py setup-key
python server.py show-key-source
python server.py run

If you intentionally want to load a local dotenv file, pass it explicitly:

kr-elections-mcp run --env-file .env
python server.py run --env-file .env

Tools

Core tools:

• list_elections
• list_districts
• list_parties
• search_candidates
• get_candidate_profile
• get_candidate_policies
• get_district_results
• get_district_summary
• get_party_vote_share_history
• get_election_overview
• assemble_candidate_packet
• diagnose_core_api_access

Additional tools:

• diagnose_full_api_access
• get_krpoltext_text
• get_krpoltext_meta
• match_krpoltext_candidate

krpoltext Text Support

This repository does not OCR live NEC booklet PDFs on demand.

Current behavior:

• get_krpoltext_text can match on candidate name plus optional year, office, district, and party hints.
• It can also match directly on booklet code.
• get_krpoltext_meta returns structured campaign booklet metadata without the long booklet text body.
• The metadata tool preserves merged candidate bio fields such as giho, birthday, age, job, edu, and career* when the upstream dataset provides them.
• match_krpoltext_candidate resolves an NEC candidate first, then ranks krpoltext rows using election scope plus stronger personal identifiers.
• Same-election same-district same-name collisions remain ambiguous unless a stronger personal identifier uniquely matches.
• The adapter now uses the current krpoltext data manifest under /data/index.json, falls back to /data/metadata.json when needed, and resolves the campaign_booklet resource.
• It understands both legacy download_url entries and newer download_urls maps from krpoltext 0.2.0, including OSF-managed artifact links.
• Enriched NEC linkage fields such as huboid are preserved when the upstream corpus provides them, and match_krpoltext_candidate can use them as strong identifiers.
• Runtime installs now include pyarrow, so enriched Parquet artifacts can be preferred by default while CSV metadata and fallback URLs remain supported.
• Legacy text fetches stay on configured krpoltext hosts, and dataset artifact fetches accept the trusted OSF-managed download hosts used by the current manifest.
• When text is available in the campaign booklet corpus, the tool returns the dataset-backed text record and corpus metadata such as code, party_name, and page_count when present.
• This public repository does not expose live NEC booklet discovery, URL derivation, or PDF download.

Example metadata lookup for Moon Jae-in in the 2017 presidential election:

get_krpoltext_meta(
  candidate_name="문재인",
  election_year=2017,
  office_name="president",
  district_name="전국 대한민국",
  party_name="더불어민주당",
  limit=3
)

Example response shape:

{
  "items": [
    {
      "record_id": "ECM0120170001_0001S",
      "code": "ECM0120170001_0001S",
      "candidate_name": "문재인",
      "office_name": "president",
      "election_year": 2017,
      "district_name": "전국 대한민국",
      "giho": "1",
      "party_name": "더불어민주당",
      "birthday": "1953-01-24",
      "age": 64,
      "edu": "경희대학교 법률학과 졸업",
      "career1": "(전)더불어민주당 당대표",
      "career2": "(전)제19대 국회의원",
      "page_count": 15,
      "has_text": true
    }
  ],
  "warnings": []
}

Example conservative NEC-to-krpoltext match:

match_krpoltext_candidate(
  candidate_name="문재인",
  sg_id="20170509",
  sg_typecode="1",
  district_name="전국 대한민국",
  limit=5
)

Example response shape:

{
  "status": "resolved",
  "message": "Resolved krpoltext metadata row from NEC election, office, district, and name context.",
  "item": {
    "code": "ECM0120170001_0001S",
    "candidate_name": "문재인",
    "district_name": "전국 대한민국",
    "giho": "1",
    "birthday": "1953-01-24",
    "age": 64,
    "match_method": "name+year+office+district+party+giho+birthday+age+sex+education+job+career",
    "match_confidence": 1.0
  },
  "warnings": [],
  "errors": []
}

The examples above use a real 2017 presidential-election row from the managed campaign booklet corpus.

Resources

• resource://nec/elections
• resource://nec/districts/{sg_id}/{sg_typecode}
• resource://nec/parties/{sg_id}/{sg_typecode}

Documentation

• API Access Guide (Korean)
• Source Status (Korean)
• Architecture (Korean)
• Data Sources (Korean)
• Examples (Korean)
• Tool Matrix (Korean)
• krpoltext Matching Guide (Korean)
• Operational Security Notes (Korean)

How to Cite

If you use this software in research, cite the software record or export citation metadata from CITATION.cff.

• DOI: 10.5281/zenodo.19490046
• Citation metadata: CITATION.cff

Example citation:

Lim T (2026). kr-elections-mcp. doi:10.5281/zenodo.19490046, Python package version 0.1.0, https://github.com/taehyun-lim/kr-elections-mcp.

Example BibTeX:

@Manual{Lim2026krElectionsMcp,
  title = {kr-elections-mcp},
  author = {Tae Hyun Lim},
  year = {2026},
  doi = {10.5281/zenodo.19490046},
  url = {https://github.com/taehyun-lim/kr-elections-mcp},
  note = {Python package version 0.1.0},
}

Testing

Tests are designed to run with mocks and stubs even without a live NEC API key.

pytest

The source-adapter tests cover krpoltext manifest resolution, trusted-host handling, and campaign booklet corpus lookups.

Limitations

• NEC policy coverage is incomplete and depends on service support by election and office.
• Live NEC API access still depends on each user's approved data.go.kr access.
• Result coverage can differ by source and historical election availability.
• krpoltext support depends on the current external dataset manifest and does not perform live OCR over NEC booklet files.

License

This project is released under the MIT License.