congressgov-mcp-server

Tools

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

`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
• `content` reads a text version's actual document text, a bounded character window at a time — pick the version with `textVersionIndex`, the window with `characterOffset`/`characterLimit`, and follow `nextOffset` to walk a full bill
• `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
• `content` reads one article's actual text, selected by `articleIndex` and bounded by `characterOffset`/`characterLimit`

`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, and not offered to clients until `CONGRESS_MIRROR_ENABLED=true`. With the flag set but the index not yet built (`bun run mirror:init`), the tool is callable and answers with an empty result and a build-the-index notice
• 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

Prompts

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:

{
  "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.

{
  "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):

{
  "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

1. Clone the repository:

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

2. Navigate into the directory:

cd congressgov-mcp-server

3. Install dependencies:

bun install

Configuration

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

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

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.