who_reps-mcp

Address → your elected officials, as an MCP server. A free, open replacement for the Google Civic Information Representatives API, which was shut down on April 30, 2025 and left a generation of civic apps broken.

Give it a U.S. street address and it returns the people who represent it — U.S. Senators, U.S. House member, Governor, and state legislators — by stitching together free public data: address → districts (Census) → officials (open congressional + state-legislator data).

Why this exists

When Google killed representativeInfoByAddress, the official guidance was: use our Divisions API for an OCD id, then go buy officeholder data from BallotReady, Cicero, or Ballotpedia. This rebuilds the free path so an agent can just answer "who represents this address?"

Quick start

The federal tier needs no API keys — the Census geocoder and the unitedstates/congress-legislators dataset are both free and key-less.

uv sync

# As an MCP server (stdio):
uv run whoreps-mcp

# Or try the data path from a terminal (no keys needed):
uv run whoreps-mcp lookup "1600 Pennsylvania Ave NW, Washington, DC 20500"
uv run whoreps-mcp lookup "2300 N Lincoln Blvd, Oklahoma City, OK 73105"
#  4 officials for 2300 N LINCOLN BLVD, ...: U.S. Senator James Lankford (R);
#  U.S. Senator Markwayne Mullin (R); U.S. Representative Stephanie I. Bice (R, 5);
#  Governor Kevin Stitt (R). State legislators omitted — set OPENSTATES_API_KEY ...

To add the state-legislator tier, get a free OpenStates key, cp .env.example .env, set OPENSTATES_API_KEY, and the same lookups will include state senators and representatives.

Use it as an MCP server

{
  "mcpServers": {
    "whoreps": {
      "command": "uv",
      "args": ["run", "whoreps-mcp"],
      "cwd": "/path/to/whoreps-mcp"
    }
  }
}

Tools

Tool	What it does
lookup_officials(address)	The headline tool. Address in, full slate out (federal + state where available), each official with party, contact, term, source, and as-of date, plus OCD divisions and coverage notes.
list_districts(address)	Just the districts/divisions for an address — congressional + state-legislative districts and OCD-IDs (the piece Google's Divisions API gave, free and self-hosted).
lookup_by_district(state, chamber, district)	Skip geocoding: senate/house (federal) or upper/lower (state).
get_official_details(official_id)	Enriched detail for one official — committees + full contact where available.

Each tool returns structured JSON plus a concise text summary.

Graceful degradation

This is a civic tool, so correctness and honesty matter:

• Federal always works, with zero keys. Missing tiers never fail the whole request — you get what's available plus coverage_notes explaining any gap.
• DC and territories return the non-voting delegate (no senators), and note that DC has a Mayor rather than a Governor and no state legislature.
• Bad/PO-box/new-construction addresses that don't geocode return an empty result with a note, not an error.
• Freshness is visible. Every official carries its source and as_of date. Governors are a vendored, dated snapshot (see docs/governors.md); everything else is fetched live and cached.

How it works

address ─▶ Census geocoder ─▶ {lat/lon, congressional district, state-leg districts, OCD divisions}
                                     │
              ┌──────────────────────┼───────────────────────┐
              ▼                      ▼                         ▼
     congress-legislators     OpenStates people.geo      governors.json
     (U.S. Senate + House)    (state legislators)        (vendored)
              └──────────────────────┼───────────────────────┘
                                     ▼
                     merge + normalize -> OfficialsResponse  (SQLite-cached)

Sources live behind sources/ so the whole flow is tested against recorded fixtures — CI is fully offline.

Development

uv run pytest        # offline suite (recorded fixtures)
uv run ruff check .  # lint

If uv run whoreps-mcp ever reports No module named 'whoreps_mcp' (a known editable-install quirk on some setups, e.g. paths with spaces), run with PYTHONPATH=src uv run whoreps-mcp ....

See SPEC.md and BUILD_PLAN.md for the design.

License

MIT.