cyanheads avatar

Openstates Mcp Server

cyanheads/openstates-mcp-server

Wraps the Open States v3 API to give Claude direct access to legislative data across all 50 states, DC, and Puerto Rico. You get 10 tools covering bill search with full-text queries and subject filters, legislator lookups by name or geolocation, committee rosters, and legislative events. The bill search returns inline sponsorships, actions, votes, and text versions when you set the include parameter, cutting down on follow-up calls. Useful for constituent research, policy tracking, and district-level analysis. Runs over stdio or streamable HTTP, and there's a public hosted instance if you want to skip local setup. Committee and event data is experimental since not all states publish it yet.

GitHub stars
3
tools
10
auth
Required
transport
STDIO, HTTP
env vars
10
last updated
Oct 28, 2026

Install

From registry metadata
$ npx add-mcp https://openstates.caseyjhand.com/mcp --name openstates

Run in your terminal. add-mcp asks which agents to add it to (Claude Code, Codex, Cursor and more). Add -g to install it for every project.

Review the command, arguments and environment values before installing. MCP servers run with your local permissions.

Other ways

Claude Code

$ claude mcp add --transport http openstates https://openstates.caseyjhand.com/mcp

Run in your terminal. Add --scope user to make it available in every project.

Tools

Verified live · 10 tools

Verified live against the running server on Nov 6, 2026.

openstates_search_billsSearch state legislative bills across all covered US jurisdictions. Supports full-text search, jurisdiction/session filtering, subject tags, sponsor lookups, and sort order. Either jurisdiction or q (full-text) is required, and pairing them is the reliable form — a q-only sear...15 params

Search state legislative bills across all covered US jurisdictions. Supports full-text search, jurisdiction/session filtering, subject tags, sponsor lookups, and sort order. Either jurisdiction or q (full-text) is required, and pairing them is the reliable form — a q-only sear...

Parameters* required
action_sincestring
ISO 8601 date — only return bills with an action after this date (e.g., "2025-01-01").
chamberstring
Filter by originating chamber. "upper" = Senate, "lower" = House/Assembly.one of upper · lower
classificationstring
Bill classification: "bill", "resolution", "constitutional amendment", etc.
created_sincestring
ISO 8601 date — only return bills first entered in Open States after this date (e.g., "2025-01-01"). Use to find newly-introduced bills, as opposed to recently-updated or recently-acted-on.
includearray
Related data to inline. "sponsorships" and "actions" cover most research needs without a separate openstates_get_bill call. "votes" adds full vote tallies and per-legislator positions.
jurisdictionstring
State name, two-letter abbreviation, or OCD-ID (e.g., "Washington", "wa", or "ocd-jurisdiction/country:us/state:wa/government"). Required unless q is provided.
pageinteger
Page number (1-indexed).default: 1
per_pageinteger
Results per page. Maximum 20. Default 10.default: 10
qstring
Full-text search across bill titles, abstracts, and text. Required unless jurisdiction is provided. Pair it with jurisdiction whenever a state is known — a q-only search over every jurisdiction tim...
sessionstring
Session identifier (e.g., "2025", "2025-2026", "2025rs"). Use openstates_get_jurisdiction with include=legislative_sessions to discover valid values. Omit to search across all sessions.
sortstring
Sort order. Use "latest_action_desc" for bills currently moving through the legislature.one of updated_asc · updated_desc · first_action_asc · first_action_desc · latest_action_asc · latest_action_descdefault: updated_desc
sponsorstring
Filter by sponsor name or OCD person ID.
sponsor_classificationstring
Filter sponsor type: "primary", "cosponsor".
subjectarray
Filter to bills tagged with one or more subject categories.
updated_sincestring
ISO 8601 date — only return bills updated after this date (e.g., "2025-01-01").
openstates_get_billFetch full detail for a specific state bill. Accepts either the three-part path (jurisdiction + session + bill_id) or a direct OCD bill ID (openstates_id from search results). Use include to request votes, actions, sponsorships, documents, and versions in one call rather than...5 params

Fetch full detail for a specific state bill. Accepts either the three-part path (jurisdiction + session + bill_id) or a direct OCD bill ID (openstates_id from search results). Use include to request votes, actions, sponsorships, documents, and versions in one call rather than...

Parameters* required
bill_idstring
Bill identifier as used by the legislature (e.g., "HB 1000", "SB 42"). Required with jurisdiction + session.
includearray
Related data to inline. "sponsorships", "actions", "votes" are most commonly needed. "versions" and "documents" provide links to bill text and fiscal notes.
jurisdictionstring
State name, abbreviation, or OCD-ID. Required when using path-based lookup with session + bill_id.
openstates_idstring
OCD bill ID from openstates_search_bills results: "ocd-bill/" followed by a UUID (e.g., "ocd-bill/4f255ccf-42a6-46ad-bbc6-0b027ebb15f2"). Preferred over the three-part path when available.
sessionstring
Session identifier. Required with jurisdiction + bill_id.
openstates_search_peopleSearch state legislators and officials by name, jurisdiction, chamber, or district, or fetch specific people by OCD person ID. Party is reported on every result but cannot be filtered on — narrow by party after the call. Either jurisdiction or id is required — a search spannin...8 params

Search state legislators and officials by name, jurisdiction, chamber, or district, or fetch specific people by OCD person ID. Party is reported on every result but cannot be filtered on — narrow by party after the call. Either jurisdiction or id is required — a search spannin...

Parameters* required
districtstring
District label (e.g., "1", "37", "At-Large"). Formats vary by state.
idarray
OCD person IDs (e.g., "ocd-person/9eddb3cd-868e-42ba-831a-b415fd7ed445"). Required unless jurisdiction is provided — it returns exactly these people, so it scopes the call on its own and needs no j...
includearray
Related data to inline. "offices" includes phone, fax, and address. "links" includes website and social links. "other_names" includes alternate/former names, "other_identifiers" cross-system IDs, a...
jurisdictionstring
State name, abbreviation, or OCD-ID. Required unless id is provided — an all-states search exceeds the upstream timeout, so every call must be scoped to a single jurisdiction or to specific person...
namestring
Name or partial name to match (case-insensitive substring). Narrows within the jurisdiction; it does not substitute for one.
org_classificationstring
Filter by role type. "upper" = Senate, "lower" = House/Assembly, "executive" = governors and executive officials, "legislature" = every legislator (both chambers merged into one paginated set, all...one of legislature · executive · lower · upper · government
pageinteger
Page number (1-indexed).default: 1
per_pageinteger
Results per page. Maximum 20.default: 10
openstates_get_legislators_by_locationFind every legislator representing a geographic coordinate — both tiers. Pass latitude and longitude to get the state senators and representatives for that location (and potentially governor/executive officials), plus the coordinate's two US Senators and its US Representative....3 params

Find every legislator representing a geographic coordinate — both tiers. Pass latitude and longitude to get the state senators and representatives for that location (and potentially governor/executive officials), plus the coordinate's two US Senators and its US Representative....

Parameters* required
includearray
Related data to inline. "offices" includes phone, fax, and address. "links" includes website and social links. "other_names" includes alternate/former names, "other_identifiers" cross-system IDs, a...
latitude*number
Latitude in decimal degrees (e.g., 47.6062 for Seattle, WA).
longitude*number
Longitude in decimal degrees (e.g., -122.3321 for Seattle, WA).
openstates_search_committeesList committees for a jurisdiction. jurisdiction is required — a request spanning all 56 jurisdictions exceeds the upstream timeout, so scope every call to a single state; use openstates_list_jurisdictions to pick one. Experimental — Open States is actively working to restore...7 params

List committees for a jurisdiction. jurisdiction is required — a request spanning all 56 jurisdictions exceeds the upstream timeout, so scope every call to a single state; use openstates_list_jurisdictions to pick one. Experimental — Open States is actively working to restore...

Parameters* required
chamberstring
Filter by chamber. "upper" = Senate, "lower" = House/Assembly. A chamber filter omits joint committees; omit chamber to include them.one of upper · lower
classificationstring
Filter to parent committees or subcommittees only. Omit for all.one of committee · subcommittee
includearray
Related data to inline. "memberships" includes the full roster with member roles. "links" includes the committee homepage and reference links, and "sources" the provenance URLs behind the record.
jurisdiction*string
State name, abbreviation, or OCD-ID. Required — an all-states request exceeds the upstream timeout, so every call must be scoped to a single jurisdiction.
pageinteger
Page number (1-indexed).default: 1
parentstring
OCD organization ID of a parent committee to retrieve its subcommittees.
per_pageinteger
Results per page. Maximum 20.default: 10
openstates_get_committeeFetch committee detail by OCD organization ID. Returns name, classification, and membership roster when include=memberships is requested. Experimental — not all states have committee data in Open States. Obtain the committee_id from openstates_search_committees.2 params

Fetch committee detail by OCD organization ID. Returns name, classification, and membership roster when include=memberships is requested. Experimental — not all states have committee data in Open States. Obtain the committee_id from openstates_search_committees.

Parameters* required
committee_id*string
OCD organization ID (from openstates_search_committees results).
includearray
Related data to inline. "memberships" includes the full roster with member roles. "links" includes the committee homepage and reference links, and "sources" the provenance URLs behind the record.
openstates_search_eventsSearch hearings, floor sessions, and committee meetings. jurisdiction is required — the Open States events endpoint has no all-states search, so scope every call to a single state; use openstates_list_jurisdictions to pick one. Experimental — most states do not publish event d...7 params

Search hearings, floor sessions, and committee meetings. jurisdiction is required — the Open States events endpoint has no all-states search, so scope every call to a single state; use openstates_list_jurisdictions to pick one. Experimental — most states do not publish event d...

Parameters* required
afterstring
ISO 8601 datetime — events starting after this time. Use to find upcoming hearings.
beforestring
ISO 8601 datetime — events starting before this time.
includearray
Related data to inline. "agenda" includes the meeting agenda with bill references. "participants" includes the committee or chamber hosting the event. "links" and "media" add related URLs and recor...
jurisdiction*string
State name, abbreviation, or OCD-ID. Required — the Open States events endpoint has no all-states search, so every call must be scoped to a single jurisdiction.
pageinteger
Page number (1-indexed).default: 1
per_pageinteger
Results per page. Maximum 20.default: 10
require_billsboolean
When true, only return events with at least one bill on the agenda. Most useful for tracking legislation through committee.default: false
openstates_get_eventFetch full event detail by OCD event ID. Returns agenda, participants, media links, and associated documents when requested via include. Experimental — event coverage is limited in Open States. Obtain the event_id from openstates_search_events.2 params

Fetch full event detail by OCD event ID. Returns agenda, participants, media links, and associated documents when requested via include. Experimental — event coverage is limited in Open States. Obtain the event_id from openstates_search_events.

Parameters* required
event_id*string
OCD event ID (from openstates_search_events results).
includearray
Related data to inline. "agenda" and "participants" are most useful; "links", "media", and "documents" add related URLs, recordings, and files, and "sources" the provenance URLs behind the record.
openstates_list_jurisdictionsList all jurisdictions covered by Open States — all 50 states, DC, and 5 US territories (American Samoa, Guam, Northern Mariana Islands, Puerto Rico, and the US Virgin Islands): 56 in total, returned complete in a single default call. Returns coverage metadata: latest bill upd...4 params

List all jurisdictions covered by Open States — all 50 states, DC, and 5 US territories (American Samoa, Guam, Northern Mariana Islands, Puerto Rico, and the US Virgin Islands): 56 in total, returned complete in a single default call. Returns coverage metadata: latest bill upd...

Parameters* required
classificationstring
Filter by jurisdiction type. Use "state" (default) for all 50 states, DC, and the 5 US territories.one of state · municipality · countrydefault: state
includearray
Related data to inline. "legislative_sessions" returns all session identifiers and date ranges — required when you need to discover valid session values for bill searches. "organizations" lists the...
pageinteger
Page number (1-indexed).default: 1
per_pageinteger
Results per page (upstream maximum 52). The default call returns the complete state inventory (56) in one response by fetching and merging the pages server-side; set a smaller value only to page ma...default: 52
openstates_get_jurisdictionFetch full metadata for a specific jurisdiction including all legislative sessions, their identifiers, and coverage dates. Use when you need to know the exact session identifier for a state before filtering bill searches — session formats vary widely (e.g., "2025", "2025rs", "...2 params

Fetch full metadata for a specific jurisdiction including all legislative sessions, their identifiers, and coverage dates. Use when you need to know the exact session identifier for a state before filtering bill searches — session formats vary widely (e.g., "2025", "2025rs", "...

Parameters* required
includearray
Related data to inline. "legislative_sessions" returns all historical and current sessions with identifiers and date ranges. "organizations" lists the jurisdiction's legislative chambers and execut...
jurisdiction_id*string
OCD jurisdiction ID, state name (e.g., "Washington"), or two-letter abbreviation (e.g., "wa").

Sponsors

Configuration

OPENSTATES_API_KEY*

Open States API key from open.pluralpolicy.com. Required to make any API requests.

OPENSTATES_DAILY_REQUEST_BUDGETdefault: 250

Maximum upstream Open States requests per rolling 24 hours. Rejects before the request is issued once spent. Defaults to the v3 free-tier daily cap.

OPENSTATES_REQUEST_TIMEOUT_MSdefault: 45000

Per-attempt upstream request deadline in milliseconds (minimum 1000). Expiry is non-retryable. Open States answers a scoped query in under a second to ~57s and its gateway gives up near 60s.

OPENSTATES_TOTAL_REQUEST_BUDGET_MSdefault: 90000

Wall-clock ceiling in milliseconds for one call across every retry attempt and the backoff between them. Bounds a slow upstream that keeps failing retryably. Must be at least OPENSTATES_REQUEST_TIMEOUT_MS; startup rejects a lower value.

MCP_LOG_LEVELdefault: info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_TRANSPORT_TYPEdefault: http

Selects the HTTP transport.

MCP_HTTP_HOSTdefault: 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault: 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault: /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault: none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Readme

@cyanheads/openstates-mcp-server

Search bills, legislators, committees, and events across all 50 US states, DC, and 5 US territories via MCP. STDIO or Streamable HTTP.

10 Tools • 1 Resource • 2 Prompts

Details

Repository
github.com/cyanheads/openstates-mcp-server
Category
Search & Web Crawling
Package
@cyanheads/openstates-mcp-server
Transport
STDIO, HTTP
Auth
Required
Registry
MCP registry, active
Resources
5
Prompts
2
Tools verified
Nov 6, 2026

More from cyanheads

Related Search & Web Crawling MCP servers

View all
1defectdojo avatarDefectDojodefectdojo/defectdojo-mcpSearch, triage and import findings in DefectDojo through its REST API v2.3stars
2domdomegg avatarOpen Food Factsdomdomegg/openfoodfacts-mcpSearch and contribute to the Open Food Facts database.3stars
3hampsterx avatarCodex Mcp Bridgehampsterx/codex-mcp-bridgeWraps Codex CLI as MCP tools: codex, review, query, search, structured, ping, listSessions.3stars
4iggredible avatarVim Mcpiggredible/vim-mcpConnect Claude Code to Vim/Neovim - query state, execute commands, search help, record macros3stars
5happygallo avatarApple Adshappygallo/apple-ads-mcpManage Apple Search Ads campaigns, keywords, budgets, and reports via API v5.3stars
6lipdog avatarFossicklipdog/fossick-mcpSearch all of GitHub from your AI agent — find libraries, drill into repos, find code patterns.3stars