Skip to main content
Glama
ElectionData MCP

ElectionData MCP

electiondata_mcp

An MCP server for Malaysian election data from ElectionData.MY.

It lets an AI chat answer questions about every federal and state election since 1955: seat histories, full contest results, candidates, parties, by-elections, polling-centre results, voter demographics, boundary maps, and live turnout on polling day. It can also run its own read-only SQL over all 208 datasets in the ElectionData.MY data lake.

Every answer lists its sources (dataset, file link, data-as-of date) and the matching electiondata.my dashboard page, so a person can check a number before using it.

Supported platforms

OS

ARM

x86

macOS

yes

yes

Windows

yes

yes

Linux

yes

yes

Python 3.12 to 3.14. Every dependency installs from a ready-made build, so no compiler is needed. CI runs the tests and the installers on all six platforms.

Related MCP server: Elections Canada MCP Server

Requirements

  • An internet connection. The server reads the public data lake at lake.electiondata.my.

  • Nothing else for the one-command install: it installs uv, which brings its own Python.

  • Optional: a free ElectionData.MY API key for three tools (live_turnout, seat_lineage, party_history). Get one at https://electiondata.my/console/. All other tools work without it.

Install

One command per platform. Each one installs uv if it is missing, installs the electiondata-mcp command, runs a self-check, and prints how to connect it.

macOS and Linux:

curl -LsSf https://raw.githubusercontent.com/azwanzuharimi/electiondata_mcp/main/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/azwanzuharimi/electiondata_mcp/main/install.ps1 | iex"

Docker (any OS, linux/amd64 and linux/arm64):

docker run -p 8000:8000 ghcr.io/azwanzuharimi/electiondata_mcp

Check an install at any time:

electiondata-mcp --check

Connect

Claude Code:

claude mcp add electiondata -- electiondata-mcp

With an API key:

claude mcp add electiondata -e ELECTIONDATA_API_KEY=your-key -- electiondata-mcp

Claude Desktop: add this to claude_desktop_config.json and restart Claude Desktop. Use the full path that the installer printed if electiondata-mcp is not found.

{
  "mcpServers": {
    "electiondata": {
      "command": "electiondata-mcp",
      "env": { "ELECTIONDATA_API_KEY": "your-key" }
    }
  }
}

Web chat apps and claude.ai: run the server over HTTP, put it behind HTTPS on a public address, and add https://your-host/mcp as a custom connector.

electiondata-mcp --http --host 0.0.0.0 --port 8000

Any MCP client that speaks Streamable HTTP can use http://your-host:8000/mcp. GET /health returns {"ok": true}.

Settings

Environment variable

Default

Meaning

ELECTIONDATA_API_KEY

not set

Key for the API tools. Never logged or returned.

RATE_LIMIT_PER_MIN

60

HTTP requests per minute per client IP. 0 turns it off.

DUCKDB_MEMORY_LIMIT

1GB

Memory limit for queries.

QUERY_TIMEOUT_S

30

Time limit per query, in seconds.

TRUST_PROXY

not set

Set to 1 behind your own reverse proxy. The rate limit then uses the last X-Forwarded-For value. Leave unset when clients connect directly, or they can change their own IP.

Public servers: also set a memory limit on the container, for example docker run --memory 2g --restart unless-stopped -p 8000:8000 ghcr.io/azwanzuharimi/electiondata_mcp. run_sql blocks the known ways to build huge values, but a container limit is the last guard.

Tools

Group

Tools

Find

search (seats, candidates, parties from loose text)

Look up

seat_history, contest_result, candidate_profile, election_summary, byelections, seat_demographics, polling_centre_results, find_seat_by_location

Analyse

swing, marginal_seats, compare, seat_features, run_sql

Discover

search_datasets, describe_dataset, join_guide, find_dashboard, data_access

API (key needed)

live_turnout, seat_lineage, party_history

Resource electiondata://guide explains names, definitions, joins, traps and worked SQL.

Accuracy

  • A seat or name that matches more than one thing returns the choices, not a guess. A match on part of a name says so in a warning.

  • run_sql can read only the data lake. Other files, other websites, writes, setting changes, table functions and functions that build huge values (range, repeat, lpad, ...) are blocked. Results stop at 2,000 rows or 5 MB, and say so with truncated.

  • A daily check runs on the live lake: one winner per contest, majority = winner minus runner-up, valid votes = sum of candidate votes, shares add up to 100%, turnout and majority formulas, and polling-centre totals = seat totals for every polling-centre file. GE-15 seat counts are checked against the published result.

  • Live turnout is marked provisional and carries the SPR snapshot time in MYT.

Development

git clone https://github.com/azwanzuharimi/electiondata_mcp
cd electiondata_mcp
uv sync
uv run pytest              # offline tests
uv run pytest -m live      # tests against the live lake (and the API if ELECTIONDATA_API_KEY is set)
uv run python scripts/build_catalogue.py   # refresh the dataset list and dashboard index

Design: docs/superpowers/specs/2026-11-15-electiondata-mcp-design.md.

Data credit

All election data comes from ElectionData.MY, the public face of the Malaysian Election Corpus (MECo), curated by Thevesh Thevananthan. The data is dedicated to the public domain under CC0 1.0. Please credit them when you use this server.

Cite the corpus as:

Thevesh Thevananthan. The Malaysian Election Corpus (MECo): Federal and State-Level Election Results from 1955 to 2025. Scientific Data (2025). doi:10.1038/s41597-025-06502-7

The official source of all Malaysian election results is the Election Commission of Malaysia (SPR).

This project is not affiliated with ElectionData.MY or SPR.

License

The code is under the MIT License. The data keeps its own CC0 dedication.

Available Tools

22 tools
byelectionsB
Read-only

All by-elections with winner, majority and turnout, newest first. Dates as YYYY-MM-DD.

Inputs: state, date_to, date_from. Returns: object

candidate_profileA
Read-only

Every contest a candidate stood in, with party at the time and result, plus totals. Get candidate_uid from search.

Inputs: candidate_uid (required). Returns: object

compareA
Read-only

Compare 2 to 5 candidates (by candidate_uid), parties or coalitions (by acronym or uid) side by side across elections.

Inputs: ids (required), kind (required). Returns: object

contest_resultB
Read-only

Full result of one contest: every candidate's votes, share and result, plus contest stats (voters, turnout, rejected votes, majority).

Inputs: seat (required), election (required), date, state. Returns: object

data_accessB
Read-only

Direct Parquet links and ready code (Python, R) to load full datasets on the user's own machine, with no row limit. Good for machine learning.

Inputs: sql, datasets. Returns: object

describe_datasetC
Read-only

Columns, coverage, join keys and download links of one dataset.

Inputs: name (required). Returns: object

election_summaryA
Read-only

Seats won and votes by coalition and party, turnout and uncontested seats for one election. GE-xx = Malaysia unless a state is given; SE-xx = one block per state.

Inputs: election (required), state. Returns: object

find_dashboardB
Read-only

Links to electiondata.my dashboard pages (English and Bahasa Malaysia) for a seat, candidate, party, coalition, election or boundary map.

Inputs: kind (required), text (required). Returns: object

find_seat_by_locationB
Read-only

Find the Parliament and state seats (optionally polling district) that contain a point. Uses the boundary maps in force in the given year (now if not given).

Inputs: lat (required), lon (required), year, include_district, +1 more. Returns: object

join_guideB
Read-only

How to join two or more datasets: the columns to join on and known traps.

Inputs: datasets (required). Returns: object

live_turnoutA
Read-only

PROVISIONAL live turnout on polling day (SPR feed, every 5 minutes, 08:00-18:00 MYT). election like 'mlk-se16'. Optional level, HHMM slot, or seat filter.

Inputs: election (required), seat, time, level. Returns: object

marginal_seatsB
Read-only

Closest contests in an election, smallest majority first, with winner and runner-up.

Inputs: election (required), limit, state, max_majority, +1 more. Returns: object

party_historyA
Read-only

A party's or coalition's seats and votes over time in one state, with old names merged (e.g. PERIKATAN into BN).

Inputs: party (required), state, election_type. Returns: object

polling_centre_resultsA
Read-only

Votes per polling stream (saluran) or polling district (dm) for one seat and election. Available for GE-12 to GE-15 and many state elections.

Inputs: seat (required), election (required), level, state. Returns: object

run_sqlA
Read-only

Run one read-only DuckDB SELECT on the lake tables. Default 200 rows, max 2000; truncated=true means more rows exist. Voter roll tables need LIMIT <= 10000 or an aggregate.

Inputs: sql (required), limit. Returns: object

search_datasetsA
Read-only

Search all 208 lake datasets by topic, column, election or state. Use before run_sql to find table names.

Inputs: query (required), group, limit. Returns: object

seat_demographicsC
Read-only

Voters in a seat by sex, age band, ethnicity and voter type, from the voter roll of an election (latest if not given).

Inputs: seat (required), state, election. Returns: object

seat_featuresB
Read-only

One row per seat for an election: turnout, majority, winner, vote share per coalition, previous result and voter demographics. Ready for modelling.

Inputs: election (required), level, state. Returns: object

seat_historyA
Read-only

Every contest held in a seat, newest first: winner, party, coalition, majority, turnout. Seat codes change over time; the history follows the seat name.

Inputs: seat (required), state. Returns: object

seat_lineageC
Read-only

A seat's results back through boundary changes, with notes on each change (from the ElectionData.MY API).

Inputs: seat (required), state. Returns: object

swingA
Read-only

Vote share per seat for one coalition or party in two elections, and the change. Seats whose name changed are listed apart.

Inputs: group (required), election_to (required), election_from (required), by, +1 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 22 tools

    Disambiguation4/5

    Most tools target clearly distinct resources or actions, and the descriptions make boundaries fairly clear. A few adjacent pairs exist, such as seat_history vs seat_lineage vs contest_result, and search vs search_datasets, but they are separable with the provided guidance.

    Naming Consistency3/5

    All names use snake_case and remain readable, but the convention is mixed: bare verbs (search, compare, swing), noun phrases (seat_history, party_history), and verb-object forms (find_seat_by_location, describe_dataset). There is no single predictable naming pattern across the set.

    Tool Count3/5

    With 22 tools, the surface is above the typical 3-15 sweet spot and spans several subdomains: results, demographics, boundary lookup, lake datasets, dashboards, and live turnout. Each tool has a plausible role, but the overall count is borderline heavy and increases selection overhead.

    Completeness5/5

    The set covers entity search, contest results, candidate and party history, seat demographics, boundary lookup, by-elections, swing and marginal analysis, polling-centre data, live turnout, dashboards, and raw dataset/SQL access. It appears to provide a very complete election-analysis surface with no obvious dead ends.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides real-time weather forecasts for locations across Malaysia by fetching data directly from MET Malaysia's API. It enables AI assistants to query today's conditions and seven-day forecasts for states, districts, and towns.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables querying Malaysian official statistics through natural language, with correct series resolution, statistical transformations, and provenance-attached data.
      11
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to answer Brazilian voters' pre-election questions from TSE open data, including comparing candidates, finding polling places, checking election dates and voting hours, and retrieving candidate details through MCP tools without personal registration data.
      7
      MIT