civicAPI MCP Server

Model Context Protocol (MCP) server for civicAPI - live and historical US election results . No API keys or authentication required.

Hosted MCP (Vercel)

Production: https://civicapi-mcp.vercel.app/mcp

Use Streamable HTTP transport (not stdio).

Cursor

{
  "mcpServers": {
    "civic-api-hosted": {
      "url": "https://civicapi-mcp.vercel.app/mcp"
    }
  }
}

Zed

"civic-api-hosted": {
  "enabled": true,
  "url": "https://civicapi-mcp.vercel.app/mcp"
}

Related MCP server: onpe-mcp

Local stdio MCP (Python)

Clone the project, then:

pip install -r python/requirements.txt
python python/server.py

Cursor (local)

{
  "mcpServers": {
    "civic-api": {
      "command": "python",
      "args": ["/absolute/path/to/civicapi-mcp/python/server.py"]
    }
  }
}

Zed (local)

"civic-api": {
  "enabled": true,
  "remote": false,
  "command": "python",
  "args": ["/absolute/path/to/civicapi-mcp/python/server.py"]
}

Tools

search_races

Search by name, country, province, district, election type, and date range. At least one filter is required.

• query — race name (slow alone; prefer geographic/date filters)

• country — ISO 3166-1 alpha-2 (US) or alpha-3 for limited-recognition states (USA)

• province — e.g. AL, JP-07

• district — English district name

• election_type

• start_date / end_date — YYYY-MM-DD

• limit — default 20, max 50000

get_race_by_id

Full race payload. Optional flags:

• generate_map / generate_map_png — rendered map (SVG or PNG)

• testdata — random test data

• data — json or csv

• embed — embed iframe JSON

• precinct — include precinct-level results

• format — map style (percentage, raw, etc.)

Non-JSON responses (CSV, SVG, PNG) are returned with _content_type and _body or _body_base64.

get_race_history

Historical snapshots for timeline/progression views. Data available for races tracked after October 9, 2025.

• Omit timestamp to list available UTC timestamps

• Set timestamp (YYYY-MM-DDTHH:MM:SS.sssZ) for a full snapshot

• Optional: generate_map, generate_map_png, light, precinct

get_election_dates

Election dates for a year (defaults to current year). Optional country and province filters.

get_election_years

All election years in the database.

get_api_status

Service health check ({"status":"ok"} when available).

Attribution

civicAPI requires attribution for non-personal projects. Link to civicapi.org or mention civicAPI in your project.

License

MIT