Racemodel MCP Server

racemodel

racemodel is a thin local bridge to the ElectionsMCP hosted MCP server, a modelling service for U.S. election races. Upstream, a user can resolve places and candidates, build a scenario, set candidate shares and turnout assumptions, apply a swing, and then read the race back as tallies, flipped seats, maps, charts and precinct-level roll-ups — including separate handling for primary races.

The bridge holds no election data and computes no forecast of its own. It serves the upstream server's tool list locally — exactly as captured from the live endpoint — and forwards each tool call upstream, returning the result untouched. Scenario and simulation state lives upstream, so writes such as creating a scenario or setting shares are the service's own modelling operations, forwarded like every other call. billing_status is a read; there is no payment, donation or purchase tool in the surface.

Tools

Geography, candidates and contests:

• resolve_geography — turn a place name or shorthand into a canonical geo id (query, required).
• resolve_candidate — find who holds or runs for a seat from a person's name (name, required).
• search_candidates — browse the candidate registry by filters without supplying a name.
• lookup_address — resolve an address (address, required) to its geography.
• list_contests — list contests for a geography (geo_id, required).
• election_calendar — the election calendar. No required arguments.

Scenarios and simulations:

• create_scenario — start a new scenario (name, required).
• list_scenarios, get_scenario (scenario_id), commit_version (scenario_id), and diff_versions (scenario_id, version_a, version_b) — manage and compare saved scenario versions.
• set_performance — set shares for a geography in a scenario (scenario_id, geo_id, shares).
• target_precincts — precinct targeting for a scenario (scenario_id, required).
• set_candidates — set the candidate list for a simulation (simulation_id, level, candidates).
• set_turnout — set turnout assumptions (simulation_id, required).
• set_race_scope — set a simulation's race scope (simulation_id, required).
• list_simulations and get_simulation (simulation_id, required) — enumerate and read simulations.
• share_simulation — share a simulation (simulation_id, required).

Views, swings and roll-ups:

• get_view, render_view and set_view — read, render or set a simulation's view (each takes simulation_id).
• render_chart — render a chart (type, required).
• add_map_comment (simulation_id, body) and list_map_comments (simulation_id) — annotate and read back a simulation's map.
• apply_uniform_swing — apply a uniform swing in percentage points (simulation_id, level, swing_pp).
• apply_swing_to_query — apply a swing scoped by a query (simulation_id, state, filter).
• get_tally — the tally at a level (simulation_id, level).
• list_flipped — seats that flipped at a level (simulation_id, level).
• compare_simulations — compare two simulations at a level (simulation_id_a, simulation_id_b, level).
• roll_up_race — roll a simulation up to the race level (simulation_id, required).

Turnout, returns and reference data:

• get_early_voting_turnout — early-voting turnout for a state (state, required).
• get_county_voter_turnout_and_registration, get_state_historical_turnout, get_live_early_vote_returns and get_precinct_election_returns — turnout, registration, historical and returns reads. No required arguments.
• get_county_officials and get_county_economic_and_wealth_profile — county reference profiles. No required arguments.
• billing_status and connection_status — account and connection reads. No required arguments.
• get_campaign_onboarding, help and get_catalog — onboarding, help and catalog reads. No required arguments.

Primaries:

• list_primary_calendar — primary calendar for a party (party, required).
• set_primary_shares — set primary shares (simulation_id, party).
• roll_up_primary — roll a primary up (simulation_id, party).
• primary_batch_edit — batch-edit a primary (simulation_id, edits).

Meta:

• call_tool — invoke another tool by name through the upstream (name, required).

Configuration

• ELECTIONSMCP_MCP_URL (optional) — override the upstream endpoint. Defaults to https://www.electionsmcp.com/mcp. (The override hook is this rebuild's own labelled reconstruction.)
• ELECTIONSMCP_API_KEY (optional) — when set, its value is sent on every upstream request under the header name the registry record pins for this remote, x-electionsmcp-key. When it is unset, no auth header is sent. (This forwarding is a labelled reconstruction; the original capture was keyless.)

Forwarding mechanics

On the first tool call the client opens a streamable HTTP session with the upstream: a JSON-RPC initialize request (protocolVersion 2025-03-26, clientInfo name racemodel), then a notifications/initialized notification, then the tools/call request carrying the caller's arguments unchanged. When the upstream answers initialize with an Mcp-Session-Id header, that value rides on every later request of the session, which is reused for the life of the process. Replies may arrive as plain JSON or as server-sent events; both are read.

Successful upstream results pass through verbatim, including any isError flag the upstream sets. Failures — a JSON-RPC error, a non-2xx status, an unreadable response, or a request that cannot be completed — come back as an isError result whose text starts with racemodel error: (this rendering is this rebuild's own labelled reconstruction).

CLI

Each tool is also a subcommand taking one JSON argument string (omit it for tools that take none):

npx @reneturcios/racemodel resolve_geography '{"query":"CA-03"}'
npx @reneturcios/racemodel create_scenario '{"name":"Baseline 2026"}'
npx @reneturcios/racemodel get_catalog
npx @reneturcios/racemodel --version

Exit codes: 0 on success, 1 on an isError result, 2 on a usage error.

MCP server

npx -y @reneturcios/racemodel mcp

MCP client config:

{
  "mcpServers": {
    "racemodel": {
      "command": "npx",
      "args": ["-y", "@reneturcios/racemodel", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/racemodel
docker run --rm ghcr.io/cloudcorprecords/racemodel --version

The container's default command is mcp, so the first form is a stdio MCP server; any other arguments reach the CLI normally.

Development

npm install
npm run build
npm test
npm run dev

The test suite runs entirely against a stubbed JSON-RPC upstream — no live network calls.

License

MIT — see LICENSE.