openstates-mcp-server

<div align="center">
  <h1>@cyanheads/openstates-mcp-server</h1>
  <p><b>Search bills, legislators, committees, and events across all 50 US states, DC, and 5 US territories via MCP. STDIO or Streamable HTTP.</b>
  <div>10 Tools • 1 Resource • 2 Prompts</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.3.2-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/openstates-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/openstates-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/openstates-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0%2B-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/openstates-mcp-server/releases/latest/download/openstates-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=openstates-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvb3BlbnN0YXRlcy1tY3Atc2VydmVyIl0sImVudiI6eyJPUEVOU1RBVEVTX0FQSV9LRVkiOiJ5b3VyLWFwaS1rZXkifX0=) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22openstates-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fopenstates-mcp-server%22%5D%2C%22env%22%3A%7B%22OPENSTATES_API_KEY%22%3A%22your-api-key%22%7D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

**Public Hosted Server:** [https://openstates.caseyjhand.com/mcp](https://openstates.caseyjhand.com/mcp)

</div>

---

## Overview

US state legislative data from the Open States v3 API — all 50 states, DC, and 5 US territories. Search and fetch bills, legislators, committees, events, and jurisdiction coverage metadata from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

### Tools

| Tool | Description |
|:---|:---|
| `openstates_search_bills` | Search state legislative bills across all covered US jurisdictions with full-text search, jurisdiction/session filtering, subject tags, and sponsor lookups |
| `openstates_get_bill` | Fetch full detail for a specific bill by OCD ID or three-part path (jurisdiction + session + bill_id) |
| `openstates_search_people` | Search state legislators and officials within a jurisdiction by name, chamber, or district, or fetch specific people by OCD person ID |
| `openstates_get_legislators_by_location` | Find every legislator representing a geographic coordinate (latitude/longitude) — state legislators and the federal delegation |
| `openstates_search_committees` | List committees for a jurisdiction (experimental — not all states have coverage) |
| `openstates_get_committee` | Fetch committee detail by OCD organization ID, with optional membership roster |
| `openstates_search_events` | Search hearings, floor sessions, and committee meetings (experimental) |
| `openstates_get_event` | Fetch full event detail including agenda, participants, and media links |
| `openstates_list_jurisdictions` | List all 56 jurisdictions (50 states, DC, and 5 US territories) covered by Open States with session identifiers and coverage metadata |
| `openstates_get_jurisdiction` | Fetch full metadata for a specific jurisdiction including all legislative sessions and their identifiers |

### Resources

| Resource | Description |
|:---|:---|
| `openstates://jurisdiction/{jurisdiction_id}` | Jurisdiction metadata including current sessions, coverage dates, and bill/people update timestamps |

All resource data is also reachable via tools. Use `openstates_get_jurisdiction` for programmatic jurisdiction lookups; the resource is useful for injecting jurisdiction context as stable reference material.

### Prompts

| Prompt | Description |
|:---|:---|
| `openstates_bill_research` | Structured framework for analyzing a state bill: summary, sponsors, committee referrals, action timeline, vote record, and related legislation |
| `openstates_legislator_profile` | Research framework for profiling a legislator: sponsored bills, committee assignments, voting record, and contact details |

## Capability reference

### `openstates_search_bills` <sub>tool</sub>

- Either `jurisdiction` or `q` is required by the schema — a `q`-only search spans all 56 jurisdictions and exceeds the upstream timeout for a common term, so pairing them is the reliable form
- Filters: `session`, `chamber` (`upper`/`lower`), `classification`, `subject` tags, `sponsor`, `sponsor_classification`, and `action_since`/`updated_since`/`created_since` ISO 8601 date filters
- `include` inlines sponsorships, actions, votes, abstracts, versions, documents, and related bills — avoids follow-up `openstates_get_bill` calls
- `sort` defaults to `updated_desc`; `sort=latest_action_desc` surfaces bills currently moving; pagination up to 20 per page (default 10)
- Empty-result notice echoes every applied filter and names the jurisdiction by name when it isn't recognized

---

### `openstates_get_bill` <sub>tool</sub>

- Lookup by `openstates_id` (preferred, from search results) or the three-part path `jurisdiction` + `session` + `bill_id`; a call missing both fails with `missing_lookup_params`
- Accepts legislature-format bill identifiers (e.g., `HB 1000`, `SB 42`)
- `include` inlines sponsorships, actions, votes, versions, documents, abstracts, other titles/identifiers, and related bills
- `not_found` when the ID or path resolves to nothing

---

### `openstates_search_people` <sub>tool</sub>

- Either `jurisdiction` or `id` (OCD person IDs) is required — an unscoped search exceeds the upstream timeout even for a name-only query
- `id` resolves any number of specific OCD person IDs in one call — the IDs that bill sponsorships and committee memberships hand back — and needs no jurisdiction alongside it
- `org_classification`: `upper`/`lower`/`executive`/`legislature` (both chambers merged, executive officials excluded); omitting it returns every officeholder including executives
- Case-insensitive substring `name` match, plus `district`; `include` adds offices, links, other_names, other_identifiers, sources
- Party is reported on every result but cannot be filtered on
- Pagination up to 20 per page

---

### `openstates_get_legislators_by_location` <sub>tool</sub>

- Pass decimal-degree `latitude`/`longitude`; does not geocode addresses
- Returns both government tiers in one call: state legislators plus the coordinate's two US Senators and one US Representative
- `jurisdiction.classification` (`state` vs `country`) is the tier discriminator — `current_role.org_classification` is not, since it's `upper`/`lower` for a US Senator exactly as for a state senator
- `stateCount`/`federalCount` enrichment fields report the tier split
- Out-of-range coordinates fail as `invalid_coordinate`; a location with no coverage returns an empty-result notice

---

### `openstates_search_committees` <sub>tool</sub>

- `jurisdiction` is required — the schema rejects an all-states request
- Filter by `classification` (`committee`/`subcommittee`) and `chamber`; `parent` scopes to one committee's subcommittees
- `include=memberships` returns the full roster with member roles
- Experimental: Open States is working to restore committee support and not all states have coverage — the output's `coverageNote` field always documents this
- Pagination up to 20 per page

---

### `openstates_get_committee` <sub>tool</sub>

- Fetch by OCD `committee_id` (from `openstates_search_committees`)
- `include=memberships` returns the roster; `include=links`/`sources` add reference URLs
- Experimental — not all states have committee data; `not_found` when the ID doesn't exist

---

### `openstates_search_events` <sub>tool</sub>

- `jurisdiction` is required — the events endpoint has no all-states search
- `after`/`before` scope to an ISO 8601 date range; `require_bills=true` filters to events with a bill on the agenda
- `include=agenda,participants` returns full meeting context
- Experimental: most states don't publish event data — an empty result may mean no coverage, not no events
- Pagination up to 20 per page

---

### `openstates_get_event` <sub>tool</sub>

- Fetch by OCD `event_id` (from `openstates_search_events`)
- `include` adds agenda, participants, links, media, and documents
- Experimental — event coverage is limited; `not_found` when the ID doesn't exist

---

### `openstates_list_jurisdictions` <sub>tool</sub>

- Returns all 56 jurisdictions (50 states, DC, and 5 US territories) in one default call — pages are merged server-side, since the upstream `per_page` ceiling of 52 no longer covers the full set
- `classification` filter defaults to `state`
- `include=legislative_sessions` returns every historical and current session identifier — required before filtering bill searches by session, since formats vary by state (e.g., `2025`, `2025-2026`, `2025rs`, `2025s1`)
- `include=organizations`/`latest_runs` add chamber/executive-body and scraper-run metadata

---

### `openstates_get_jurisdiction` <sub>tool<