io.github.cyanheads/congressgov-mcp-server

Official

by cyanheads · TypeScript

Access U.S. congressional data - bills, votes, members, committees - via MCP.

Access U.S. congressional bills, votes, members, and committee data.

Topics

congresslegislationlegislative-datamcpmcp-servermodel-context-protocoltypescriptcongress-govbillsus-governmentcyanheads

README.md12 KBView on GitHub

<div align="center"> <h1>@cyanheads/congressgov-mcp-server</h1> <p><b>Access U.S. congressional data - bills, votes, members, committees - through MCP. STDIO & Streamable HTTP.</b> <div>11 Tools • 5 Resources • 2 Prompts</div> </p> </div> <div align="center">

</div> <div align="center">

Public Hosted Server: https://congressgov.caseyjhand.com/mcp

</div>

Tools

Eleven read-only tools for querying U.S. legislative data:

Tool	Description
`congressgov_bill_lookup`	Browse and retrieve U.S. legislative bill data — actions, sponsors, summaries, text, related bills
`congressgov_enacted_laws`	Browse enacted public and private laws by congress
`congressgov_member_lookup`	Discover congressional members by state/district/congress, retrieve legislative portfolios
`congressgov_committee_lookup`	Browse congressional committees and their legislation, reports, and nominations
`congressgov_roll_votes`	Retrieve House and Senate roll call votes and individual member voting positions
`congressgov_senate_nominations`	Browse presidential nominations to federal positions and track the Senate confirmation process
`congressgov_bill_summaries`	Browse recent CRS bill summaries — the "what's happening" feed
`congressgov_crs_reports`	Browse and retrieve nonpartisan CRS policy analysis reports
`congressgov_committee_reports`	Browse and retrieve committee reports accompanying legislation
`congressgov_daily_record`	Browse the daily Congressional Record — floor speeches, debates, and proceedings
`congressgov_search_bills`	Keyword-search bill titles and CRS summaries via a local full-text mirror (opt-in, off by default)

`congressgov_bill_lookup`

Browse and retrieve U.S. legislative bill data from Congress.gov.

Filter by congress number, bill type, and update-date range
Retrieve detailed sub-resources: actions, amendments, committees, cosponsors, related bills, subjects, summaries, text versions, and titles
list defaults to order='recent' (newest update-date first); pass order='oldest' for ascending
Pagination support for browsing large result sets

`congressgov_member_lookup`

Discover congressional members and their legislative activity.

Browse by state, district, congress number, and chamber
Retrieve a member's sponsored and cosponsored legislation
Look up specific members by bioguide ID

`congressgov_committee_lookup`

Browse congressional committees and their legislation, reports, and nominations.

Filter by chamber (House, Senate, Joint)
Retrieve committee bills, reports, and nominations
Detail and sub-resource lookups need only committeeCode — chamber is auto-detected from the code
Committee bills default to order='recent' (newest-first); pass order='oldest' for ascending update-date order

`congressgov_roll_votes`

Retrieve House and Senate roll call votes and individual member voting positions.

Set chamber to house (default, from the Congress.gov API) or senate (from the Senate's official LIS feed — the API exposes no Senate votes)
list browses votes by congress and session, newest first; pass order='oldest' for ascending
get returns the question, result, tallies, party breakdown, and associated bill/nomination/amendment
members returns each member's recorded position

`congressgov_bill_summaries`

Browse recent CRS bill summaries.

Filter by congress and bill type
Browse chronologically to see what's moving through Congress

`congressgov_crs_reports`

Browse and retrieve CRS reports — nonpartisan policy analyses written by subject-matter experts at the Library of Congress.

Browse the full report catalog
Retrieve individual reports by product number

`congressgov_daily_record`

Browse the daily Congressional Record — floor speeches, debates, and legislative text published each day Congress is in session.

Browse volumes by congress number
Retrieve specific issue articles

`congressgov_search_bills`

Keyword-search bill titles and CRS summaries against a local full-text mirror — the discovery path the Congress.gov API itself lacks.

Opt-in: off by default. Requires CONGRESS_MIRROR_ENABLED=true and a locally built index (bun run mirror:init) — until then the tool is visible but not callable
Narrow with congress, billType, and originChamber filters
Returns BM25-ranked matches with each bill's derived id, ready for a follow-up congressgov_bill_lookup call

Resources

URI Pattern	Description
`congress://current`	Current congress number, session dates, chamber info
`congress://bill-types`	Reference table of valid bill type codes
`congress://member/{bioguideId}`	Member profile by bioguide ID
`congress://bill/{congress}/{billType}/{billNumber}`	Bill detail by congress, type, and number
`congress://committee/{committeeCode}`	Committee detail by committee code

Prompts

Prompt	Description
`congressgov_bill_analysis`	Structured framework for analyzing a bill
`congressgov_legislative_research`	Research framework for a policy area across Congress

Features

Built on @cyanheads/mcp-ts-core:

Declarative tool definitions — single file per tool, framework handles registration and validation
Unified error handling across all tools
Pluggable auth (none, jwt, oauth)
Swappable storage backends: in-memory, filesystem, Supabase
Structured logging with optional OpenTelemetry tracing
Runs locally (stdio/HTTP) or in Docker from the same codebase

Congress.gov-specific:

Type-safe client for the Congress.gov REST API v3
Optional API key from api.data.gov — defaults to DEMO_KEY (30 req/hr); own key gets 5,000 req/hr
Automatic pagination and response normalization
Rate limiting awareness
All tools are read-only and idempotent

Getting started

Public Hosted Instance

A public instance is available at https://congressgov.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

json

{
  "mcpServers": {
    "congressgov-mcp-server": {
      "type": "streamable-http",
      "url": "https://congressgov.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file.

json

{
  "mcpServers": {
    "congressgov-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/congressgov-mcp-server@latest"],
      "env": {
        "CONGRESS_API_KEY": "your-api-key"
      }
    }
  }
}

Or with npx (no Bun required):

json

{
  "mcpServers": {
    "congressgov-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/congressgov-mcp-server@latest"],
      "env": {
        "CONGRESS_API_KEY": "your-api-key"
      }
    }
  }
}

Get a free API key at api.data.gov/signup for 5,000 req/hr. Without a key the server falls back to DEMO_KEY (30 req/hr).

Prerequisites

Bun v1.3.2 or higher.

Installation

Clone the repository:

git clone https://github.com/cyanheads/congressgov-mcp-server.git

Navigate into the directory:

cd congressgov-mcp-server

Install dependencies:

bun install

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:

Variable	Description	Default
`CONGRESS_API_KEY`	Optional. API key from api.data.gov. Omit to use `DEMO_KEY` (30 req/hr); own key: 5,000 req/hr.	`DEMO_KEY`
`CONGRESS_API_BASE_URL`	Congress.gov API base URL	`https://api.congress.gov/v3`
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`	`stdio`
`MCP_HTTP_PORT`	HTTP server port	`3010`
`MCP_AUTH_MODE`	Authentication: `none`, `jwt`, or `oauth`	`none`
`MCP_LOG_LEVEL`	Log level (`debug`, `info`, `warning`, `error`, etc.)	`info`
`LOGS_DIR`	Directory for log files (Node.js only).	`<project-root>/logs`
`STORAGE_PROVIDER_TYPE`	Storage backend	`in-memory`
`OTEL_ENABLED`	Enable OpenTelemetry instrumentation (spans, metrics, completion logs)	`false`

Running the server

Local development

Build and run the production version:

bun run rebuild
bun run start:http   # or start:stdio

Run checks and tests:

bun run devcheck     # Lints, formats, type-checks
bun run test         # Runs test suite

Docker

docker build -t congressgov-mcp-server .
docker run -e CONGRESS_API_KEY=your-api-key -p 3010:3010 congressgov-mcp-server

Project structure

Directory	Purpose
`src/mcp-server/tools/definitions/`	Tool definitions (`*.tool.ts`). Eleven Congress.gov tools.
`src/mcp-server/resources/definitions/`	Resource definitions. Congress, bill, member, and committee resources.
`src/mcp-server/prompts/definitions/`	Prompt definitions. Bill analysis and legislative research prompts.
`src/services/congress-api/`	Congress.gov API client — auth, pagination, rate limiting.
`src/config/`	Server-specific environment variable parsing and validation with Zod.
`tests/`	Unit and integration tests, mirroring the `src/` structure.

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

Handlers throw, framework catches — no try/catch in tool logic
Use ctx.log for logging, ctx.state for storage
All tools are read-only with readOnlyHint: true and idempotentHint: true

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

Install

Configuration

Environment variables

CONGRESS_API_KEY

API key from api.data.gov — optional (falls back to DEMO_KEY: 30 req/hr). Own key: 5000 req/hr. Free signup at api.data.gov.

MCP_LOG_LEVELdefault info

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

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'.

claude_desktop_config.json

{
  "mcpServers": {
    "congressgov-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/congressgov-mcp-server@0.4.1",
        "run",
        "start:stdio"
      ],
      "env": {
        "CONGRESS_API_KEY": "<YOUR_CONGRESS_API_KEY>",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}