Bill Commons

Search 209k+ US state bills, all 50 states + DC: full text, sponsors, votes, status. Free.

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "bill-commons": {
      "command": "npx",
      "args": [
        "-y",
        "bill-commons"
      ]
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

Bill Commons

Bill Commons is a public, open-source legislative search platform covering the current session/biennium for all 50 U.S. states plus DC. It provides a web search UI, a REST API, an MCP (Model Context Protocol) server, and a public status/coverage page. Public infrastructure first: no paywall on ordinary search or reasonable API use — anonymous callers get a generous daily cap (2,000 requests/day per IP, 5,000/day per /24 subnet); a free API key raises that further, and only high-volume/bulk use is paid. See /docs/bulk for API keys and full-corpus snapshots.

See docs/architecture/ARCHITECTURE.md for the locked architecture and data model.

Production

Web: https://billcommons.org (search UI + public status/coverage page at https://status.billcommons.org)
API: https://api.billcommons.org/api/v1 — interactive OpenAPI docs at https://api.billcommons.org/docs
MCP (Streamable HTTP): https://mcp.billcommons.org/mcp

Hosted on Railway (project billcommons: api, mcp, worker services + managed Postgres) and Vercel (project billcommons-web). See docs/operations/deployment-runbook.md for the full deploy/rollback procedure.

Use with Claude (or any MCP client)

The hosted MCP server gives AI assistants direct access to all 209k+ bills — no API key, no setup beyond one command:

Terminal

claude mcp add bill-commons --transport http https://mcp.billcommons.org/mcp

Claude Desktop: Settings → Connectors → Add custom connector with URL https://mcp.billcommons.org/mcp. Cursor and other clients: add the same URL as a Streamable HTTP server in mcp.json.

Ten tools including search_legislation, get_bill_record, compare_bill_versions, and trace_legislative_history. Full walkthrough (including REST recipes for agents without MCP): https://billcommons.org/docs/agents

Architecture at a glance

Code

                    ┌─────────────┐
   users ─────────▶ │  apps/web   │  Next.js, billcommons.org
                    │ (Vercel)    │  status.billcommons.org (rewrite → /coverage)
                    └──────┬──────┘
                           │ HTTPS (NEXT_PUBLIC_API_BASE)
                           ▼
                    ┌─────────────┐        ┌──────────────┐
                    │  apps/api   │◀──────▶│  apps/mcp    │  Streamable HTTP
                    │  FastAPI    │        │  10 MCP tools│  mcp.billcommons.org
                    │ /api/v1     │        └──────────────┘
                    │ api.billcommons.org
                    └──────┬──────┘
                           │ reads (SQLAlchemy)
                           ▼
                    ┌─────────────────────────────┐
                    │   Postgres 16 (Railway)      │
                    │  jurisdictions, sessions,     │
                    │  bills, actions, sponsorships,│
                    │  votes, ingest_jobs, coverage  │
                    └──────────────▲──────────────┘
                                   │ writes (idempotent upserts)
                    ┌──────────────┴──────────────┐
                    │  workers/ingest (worker svc)  │
                    │  autoboot: seed → bootstrap →│
                    │  schedule-refresh → job loop  │
                    │  sources: Open States bulk CSV│
                    │  (T2 bootstrap) + v3 API (T2  │
                    │  incremental, OPENSTATES_API_ │
                    │  KEY) + full-text fetcher     │
                    └──────────────┬──────────────┘
                                   ▼
                    RawStore (filesystem, RAWSTORE_ROOT
                    volume in prod) — sha256-addressed
                    raw payload archive

packages/schema (SQLAlchemy models + Alembic) is the single source of truth every other package/app imports from — no service owns its own copy of the data model.

Monorepo layout

Code

apps/web        Next.js 15 (App Router, TS) — search UI + status page
apps/api        FastAPI — REST API (/api/v1)
apps/mcp        MCP server (Streamable HTTP, mounted at /mcp)
workers/ingest  Ingestion workers, job queue, per-source adapters
packages/schema SQLAlchemy models + Alembic migrations (single source of truth)
packages/shared Shared Python utils: bill-number normalization, rawstore, http client
packages/source-registry  Per-jurisdiction source registry (data + loader)
packages/search Search SQL builders / query parsing
infra/docker    Dockerfiles + docker-compose.yml (local stack)
infra/deployment Railway/Vercel configs, DNS runbook
docs/           Architecture, API, sources, operations, state-coverage docs
data/registry   Machine-readable registry (sessions, sources)

Local development setup

Prerequisites

Python 3.12
PostgreSQL 16 (with pg_trgm, unaccent, pgcrypto extensions available)
Node.js 20+ (for apps/web)

Python environment

bash

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

This installs packages/schema and packages/shared as editable installs (single source of truth for the data model + shared utils), plus the worker package: .venv/bin/pip install -e workers/ingest. Install the API package too if you're working on it: .venv/bin/pip install -e apps/api.

Database

Set DATABASE_URL in your environment (or in ~/.config/billcommons/.env, which is read as a fallback and is never committed):

Code

DATABASE_URL=postgresql://user:password@host:port/dbname

Requires Postgres 16 with the pg_trgm and unaccent extensions available (created by migration 0001). Run migrations:

bash

cd packages/schema
../../.venv/bin/alembic upgrade head

Seeding data locally

bash

# Seed all 51 jurisdictions/sessions/coverage rows from the registry:
.venv/bin/python -m billcommons_ingest seed-registry

# Download a state's Open States bulk-CSV zip and ingest it (see
# docs/operations/ingestion-runbook.md for the full command reference):
python3 workers/ingest/download_bulk.py --only NC
.venv/bin/python -m billcommons_ingest bootstrap --state NC --zip data/bulkzips/NC_2025.zip
.venv/bin/python -m billcommons_ingest recompute-coverage

Running the apps locally

bash

# API (FastAPI, http://localhost:8000, docs at /docs)
.venv/bin/uvicorn main:app --app-dir apps/api --reload --port 8000

# MCP server (Streamable HTTP, http://localhost:8400/mcp by default)
.venv/bin/python apps/mcp/server.py

# Ingestion worker (long-running queue loop; runs schedule-refresh
# periodically inside the same process)
.venv/bin/python -m billcommons_ingest worker

# Web app (Next.js — separate from the Python stack)
cd apps/web
npm install
NEXT_PUBLIC_API_BASE=http://localhost:8000 npm run dev

Tests

bash

.venv/bin/pytest packages/shared/tests
.venv/bin/pytest workers/ingest/tests
.venv/bin/pytest apps/api/tests

Running the stack locally with Docker

bash

cd infra/docker
docker compose up --build

This brings up Postgres, the API, the ingestion worker, and the MCP server. The web app (apps/web) is run separately via npm run dev during local development (see infra/docker/docker-compose.yml for the placeholder service definition).

Documentation

docs/architecture/ARCHITECTURE.md — locked architecture + data model
docs/SPEC.md — requirements digest / acceptance gate
docs/operations/deployment-runbook.md — Railway/Vercel deploy, rollback, smoke checklist
docs/operations/ingestion-runbook.md — CLI reference, job queue, refresh cadence
docs/operations/source-failure-runbook.md — stale zips, 401/429, robots blocks
docs/operations/backup-restore.md — pg_dump/restore, raw-data re-fetch
docs/operations/add-a-jurisdiction.md — onboarding a new territory/state
docs/state-coverage/methodology.md — coverage state machine, GREEN criteria
docs/api/examples.md — curl/Python/JavaScript examples against the live API
docs/sources/openstates-csv.md — Open States bulk CSV column mapping

License

Apache-2.0. See LICENSE and NOTICE for data attribution (Open States / Plural Policy, public-domain legislative data).

Contributing

See CONTRIBUTING.md. This project follows the Contributor Covenant.

Security

See SECURITY.md for responsible disclosure.

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Bill Commons

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "bill-commons": { "command": "npx", "args": ["-y", "bill-commons"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/bill-commons?style=directory)](https://allmcps.com/mcp/bill-commons)

HTML Embed

<a href="https://allmcps.com/mcp/bill-commons"><img src="https://allmcps.com/api/badge/bill-commons?style=directory" alt="Bill Commons on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.

★ Spotlight Slot

Feature Your MCP Server

Get maximum visibility for your server across our directory, search results, and detail pages.

Spotlight Your Server

Own this project?

This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge — proof is checked automatically, then reviewed by our team.

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to Bill Commons →Install in Claude Desktop Install in Cursor Install in VS Code

Bill Commons

Search 209k+ US state bills, all 50 states + DC: full text, sponsors, votes, status. Free.

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "bill-commons": {
      "command": "npx",
      "args": [
        "-y",
        "bill-commons"
      ]
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

Bill Commons

See docs/architecture/ARCHITECTURE.md for the locked architecture and data model.

Production

Web: https://billcommons.org (search UI + public status/coverage page at https://status.billcommons.org)
API: https://api.billcommons.org/api/v1 — interactive OpenAPI docs at https://api.billcommons.org/docs
MCP (Streamable HTTP): https://mcp.billcommons.org/mcp

Use with Claude (or any MCP client)

The hosted MCP server gives AI assistants direct access to all 209k+ bills — no API key, no setup beyond one command:

Terminal

claude mcp add bill-commons --transport http https://mcp.billcommons.org/mcp

Claude Desktop: Settings → Connectors → Add custom connector with URL https://mcp.billcommons.org/mcp. Cursor and other clients: add the same URL as a Streamable HTTP server in mcp.json.

Architecture at a glance

Code

                    ┌─────────────┐
   users ─────────▶ │  apps/web   │  Next.js, billcommons.org
                    │ (Vercel)    │  status.billcommons.org (rewrite → /coverage)
                    └──────┬──────┘
                           │ HTTPS (NEXT_PUBLIC_API_BASE)
                           ▼
                    ┌─────────────┐        ┌──────────────┐
                    │  apps/api   │◀──────▶│  apps/mcp    │  Streamable HTTP
                    │  FastAPI    │        │  10 MCP tools│  mcp.billcommons.org
                    │ /api/v1     │        └──────────────┘
                    │ api.billcommons.org
                    └──────┬──────┘
                           │ reads (SQLAlchemy)
                           ▼
                    ┌─────────────────────────────┐
                    │   Postgres 16 (Railway)      │
                    │  jurisdictions, sessions,     │
                    │  bills, actions, sponsorships,│
                    │  votes, ingest_jobs, coverage  │
                    └──────────────▲──────────────┘
                                   │ writes (idempotent upserts)
                    ┌──────────────┴──────────────┐
                    │  workers/ingest (worker svc)  │
                    │  autoboot: seed → bootstrap →│
                    │  schedule-refresh → job loop  │
                    │  sources: Open States bulk CSV│
                    │  (T2 bootstrap) + v3 API (T2  │
                    │  incremental, OPENSTATES_API_ │
                    │  KEY) + full-text fetcher     │
                    └──────────────┬──────────────┘
                                   ▼
                    RawStore (filesystem, RAWSTORE_ROOT
                    volume in prod) — sha256-addressed
                    raw payload archive

packages/schema (SQLAlchemy models + Alembic) is the single source of truth every other package/app imports from — no service owns its own copy of the data model.

Monorepo layout

Code

apps/web        Next.js 15 (App Router, TS) — search UI + status page
apps/api        FastAPI — REST API (/api/v1)
apps/mcp        MCP server (Streamable HTTP, mounted at /mcp)
workers/ingest  Ingestion workers, job queue, per-source adapters
packages/schema SQLAlchemy models + Alembic migrations (single source of truth)
packages/shared Shared Python utils: bill-number normalization, rawstore, http client
packages/source-registry  Per-jurisdiction source registry (data + loader)
packages/search Search SQL builders / query parsing
infra/docker    Dockerfiles + docker-compose.yml (local stack)
infra/deployment Railway/Vercel configs, DNS runbook
docs/           Architecture, API, sources, operations, state-coverage docs
data/registry   Machine-readable registry (sessions, sources)

Local development setup

Prerequisites

Python 3.12
PostgreSQL 16 (with pg_trgm, unaccent, pgcrypto extensions available)
Node.js 20+ (for apps/web)

Python environment

bash

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

Database

Set DATABASE_URL in your environment (or in ~/.config/billcommons/.env, which is read as a fallback and is never committed):

Code

DATABASE_URL=postgresql://user:password@host:port/dbname

Requires Postgres 16 with the pg_trgm and unaccent extensions available (created by migration 0001). Run migrations:

bash

cd packages/schema
../../.venv/bin/alembic upgrade head

Seeding data locally

bash

# Seed all 51 jurisdictions/sessions/coverage rows from the registry:
.venv/bin/python -m billcommons_ingest seed-registry

# Download a state's Open States bulk-CSV zip and ingest it (see
# docs/operations/ingestion-runbook.md for the full command reference):
python3 workers/ingest/download_bulk.py --only NC
.venv/bin/python -m billcommons_ingest bootstrap --state NC --zip data/bulkzips/NC_2025.zip
.venv/bin/python -m billcommons_ingest recompute-coverage

Running the apps locally

bash

# API (FastAPI, http://localhost:8000, docs at /docs)
.venv/bin/uvicorn main:app --app-dir apps/api --reload --port 8000

# MCP server (Streamable HTTP, http://localhost:8400/mcp by default)
.venv/bin/python apps/mcp/server.py

# Ingestion worker (long-running queue loop; runs schedule-refresh
# periodically inside the same process)
.venv/bin/python -m billcommons_ingest worker

# Web app (Next.js — separate from the Python stack)
cd apps/web
npm install
NEXT_PUBLIC_API_BASE=http://localhost:8000 npm run dev

Tests

bash

.venv/bin/pytest packages/shared/tests
.venv/bin/pytest workers/ingest/tests
.venv/bin/pytest apps/api/tests

Running the stack locally with Docker

bash

cd infra/docker
docker compose up --build

Documentation

docs/architecture/ARCHITECTURE.md — locked architecture + data model
docs/SPEC.md — requirements digest / acceptance gate
docs/operations/deployment-runbook.md — Railway/Vercel deploy, rollback, smoke checklist
docs/operations/ingestion-runbook.md — CLI reference, job queue, refresh cadence
docs/operations/source-failure-runbook.md — stale zips, 401/429, robots blocks
docs/operations/backup-restore.md — pg_dump/restore, raw-data re-fetch
docs/operations/add-a-jurisdiction.md — onboarding a new territory/state
docs/state-coverage/methodology.md — coverage state machine, GREEN criteria
docs/api/examples.md — curl/Python/JavaScript examples against the live API
docs/sources/openstates-csv.md — Open States bulk CSV column mapping

License

Apache-2.0. See LICENSE and NOTICE for data attribution (Open States / Plural Policy, public-domain legislative data).

Contributing

See CONTRIBUTING.md. This project follows the Contributor Covenant.

Security

See SECURITY.md for responsible disclosure.

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Bill Commons

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "bill-commons": { "command": "npx", "args": ["-y", "bill-commons"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/bill-commons?style=directory)](https://allmcps.com/mcp/bill-commons)

HTML Embed

<a href="https://allmcps.com/mcp/bill-commons"><img src="https://allmcps.com/api/badge/bill-commons?style=directory" alt="Bill Commons on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

★ Spotlight Slot

Feature Your MCP Server

Get maximum visibility for your server across our directory, search results, and detail pages.

Spotlight Your Server

Own this project?

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to Bill Commons →Install in Claude Desktop Install in Cursor Install in VS Code