Overview

US congressional data from Congress.gov and the Senate's official vote feed: bills, amendments, enacted laws, members, committees, roll call votes, nominations, CRS and committee reports, and the Congressional Record. Browse legislative activity, read bill and report text, and follow nominations through Senate confirmation.

Tools

Resources

Bill, member, and committee data is also reachable through congressgov_bill_lookup, congressgov_member_lookup, and congressgov_committee_lookup (operation get), since many MCP clients are tool-only and never surface resources.

Prompts

Agent skill

congressgov-guide guides research across bills, laws, members, committees, votes, and floor debate. It covers identifier provenance, discovery limits, and version-specific document evidence. The guide ships with plugin installs, npm, MCPB, and Docker, and is served over MCP through the Skills extension and its skill:// resource.

Capability reference

congressgov_bill_lookup _tool

• list browses one congress, narrowed by billType and a fromDateTime/toDateTime range on the record's update date, newest first unless order: 'oldest'; get, actions, amendments, cosponsors, committees, subjects, summaries, text, titles, related, and content need congress + billType + billNumber
• type and number from a bill row are accepted as billType and billNumber; bill type codes are case-insensitive. Send one name per field, since canonical and alias keys together are rejected
• content reads the text version at textVersionIndex (0 is the most recent) and returns one character window in content.text with totalCharacters, truncated, and nextOffset
• summaries takes an optional versionCode (00 introduced, 49 public law) and pages like congressgov_bill_summaries, using characterOffset/characterLimit
• fromDateTime/toDateTime apply to list only; other operations are served with a notice naming them as ignored
• An actions row that records exactly one roll call vote carries rollVote, the congressgov_roll_votes arguments for it (House votes from the 115th Congress, Senate from the 101st)

congressgov_amendment_lookup _tool

• An amendment is congress + amendmentType (hamdt, samdt, or suamdt, in any letter case; suamdt, Senate unprinted amendments, exists only in the 97th and 98th Congresses) + amendmentNumber (a number or a digit string). Those identifiers come from congressgov_bill_lookup amendments rows, House congressgov_roll_votes rows (amendmentType/amendmentNumber), and congressgov_member_lookup sponsored/cosponsored rows, which carry the number and the type only in the row's url
• list browses one congress, optionally one amendmentType, newest update first unless order: 'oldest', with fromDateTime/toDateTime on the record's update date; it refuses amendmentNumber (incompatible_identity). Other operations are served with a notice naming a date bound as ignored
• get returns the sponsor, purpose, description, the bill or amendment amended, and the latest action; actions, cosponsors, amendments (amendments to this amendment), and text page the sub-resources
• An actions row that records exactly one roll call vote carries rollVote, the congressgov_roll_votes arguments for it
• text lists the published text versions, each a Congressional Record page; content reads the HTML of the version at textVersionIndex as one characterOffset/characterLimit window. The page prints the amendment amid the surrounding floor proceedings, so it is often far longer than the amendment

congressgov_enacted_laws _tool

• list browses one congress, optionally by lawType (pub or priv), the enactment filter congressgov_bill_lookup lacks; get needs lawType + lawNumber, taken from a list row's laws[].number (118-90) or its bare number (90)
• get returns the origin bill record, with the law citation on its laws[] array

congressgov_member_lookup _tool

• No name search: list filters by stateCode (plus district, 0 for at-large, which requires stateCode), congress, and currentMember
• get returns the profile for a bioguideId (e.g. P000197); sponsored and cosponsored return that member's legislation

congressgov_committee_lookup _tool

• committeeCode is a chamber prefix (h/s/j), letters, and a 2-digit suffix (e.g. hsju00); get, bills, reports, and the Senate-only nominations infer chamber from the prefix, and read it from the committee roster when the prefix's chamber doesn't hold the code (jsat00 is a Senate committee); chamber is accepted in any letter case, as committee rows carry it (Senate)
• A committee name in committeeCode resolves when exactly one committee matches, and otherwise returns candidate rows with a notice. With chamber set, only that chamber's committees are searched, so a name unique within one chamber (judiciary with chamber: 'senate') resolves in one step, and a lone fuzzy match there comes back as a candidate row; without chamber, a lone fuzzy match resolves and the notice says it is approximate. The resolved committee is read in the chamber its roster row names. list with filter name-matches every committee in scope, and fuzzy hits carry approximate: true
• bills is newest first by default (order), and its rows carry no titles, so chain congressgov_bill_lookup get per row

congressgov_roll_votes _tool

• chamber is house (default, Congress.gov API) or senate (the Senate's LIS feed), in any letter case; every call needs congress + session (1 or 2), and get/members add voteNumber, which resets each session and is specific to one chamber
• members filters by bioguideId (House only), stateCode, and party, all applied before paging: pagination.count counts the matches and memberFilter.rosterCount is the roster size. A Senate call with bioguideId fails unsupported_filter, whichever source answers, since the Senate feed identifies senators by its own IDs; filter senators by stateCode
• list and get serve the call and name any of those filters as ignored
• A congress's first year is session 1 and its second year session 2, but a second session can run into January 1–3 of the following year (the 116th Congress's second session voted on 2021-01-01)
• list is newest first unless order: 'oldest'; get returns the question, result, tallies, and party breakdown, and members returns each member's position
• House votes are covered from the 115th Congress (2017) and Senate votes from the 101st (1989), and Senate rows pair the feed's year-less voteDate with a derived voteDateIso (rows Voteview serves carry voteDateIso alone)
• A House get or members call below the 115th Congress fails not_found before any request, naming that coverage and pointing at the Clerk's vote XML in a bill action's recordedVotes
• When the Senate LIS feed can't answer a list, get, or members call (senate.gov refusing automated clients with HTTP 403 or its firewall page, another 4xx, a 5xx or timeout after retries, an empty body), Voteview's per-congress files answer instead, and the response carries source (name, url, latestVote, and Voteview's requested citation). Voteview's President's positions are dropped, and a vote after source.latestVote is not_found naming that vote. The feed's own not-found page, a cancelled call, a spent call budget, and congresses before the 101st never fall back. When the feed answers, the output is unchanged and Voteview is not contacted. Voteview's files are cached for 1 hour. House votes are unaffected

congressgov_senate_nominations _tool

• list browses one congress, newest update first; fromDateTime/toDateTime filter on the record's update date, not its received or action date. get, actions, committees, hearings, and nominees need a nominationNumber (1000 for PN1000; PN730-2, pn730-2, and 730-2 are equivalent), and nominees also needs an ordinal from the nominees array get returns
• Multi-part nominations (e.g. PN851) keep their activity on partitioned children (851-1, 851-2, …); an empty sub-resource call on the bare number returns a notice pointing there
• An action whose text cites its own Senate record vote (Record Vote Number: 225.) carries rollVote — { chamber: 'senate', congress, session, voteNumber }, the congressgov_roll_votes arguments for that vote. Every citing actions row gets one, cloture votes included, and so does latestAction on list rows and get; votes before the 101st Congress get none

congressgov_bill_summaries _tool

• Optional congress and billType (which requires congress); fromDateTime/toDateTime filter on the summary's update time, not the bill's action date, and cover the last 7 days when both are omitted
• A page returns limit rows, and pagination.nextOffset resumes; a summary over 25,000 characters arrives windowed with textTotalCharacters, textTruncated, and textNextOffset
• For one bill's summaries, or to read a windowed summary to the end, use congressgov_bill_lookup summaries

congressgov_crs_reports _tool

• list browses the catalog, newest update first; fromDateTime/toDateTime filter on the date Congress.gov last updated a report, not its publication date. get and content take a reportNumber: letters then digits (R40097, RL33612, IF12345) or, for older reports, two digit groups joined by a hyphen (96-548), in any case
• id, reportId, and report_id are accepted as reportNumber; send only one identifier key
• get returns authors, topics, summary, and download formats
• content reads the report's HTML version as plain text in a characterOffset/characterLimit window (script, style, and comments dropped; tables as tab-separated rows). A PDF-only report fails format_unavailable, naming its PDF URL

congressgov_committee_reports _tool

• list browses one congress, optionally by reportType (hrpt House, srpt Senate, erpt Executive). fromDateTime/toDateTime filter on the date Congress.gov last updated a report record, and conference selects conference reports (true) or the others (false); get, text, and content need reportType + reportNumber
• get returns the citation, title, committees, and associated bill; text lists {type, url} format links, and content reads the report as one character window
• A multi-part report is filed as one record per part: part (default 1) selects one on get, text, and content, and parts lists every part number when there is more than one. A part the report lacks fails not_found, naming the parts it has

congressgov_daily_record _tool

• Navigation runs list (volumes) → issues (by volumeNumber) → articles (by volumeNumber + issueNumber)
• content reads the article at articleIndex (0-based across the issue) as one character window; Record articles publish Formatted Text and PDF only, so format: 'xml' fails as format_unavailable

congressgov_search_bills _tool

• query keywords (AND-combined) over bill titles and CRS summaries, narrowed by congress, billType, and originChamber; limit 1–100, offset pagination
• BM25-ranked rows carry billId plus congress/billType/billNumber for congressgov_bill_lookup, and a summaryPreview; policy area and full bill text are not indexed
• Every response names the searchable congresses in mirroredCongresses; a congress outside them returns an empty result with a notice pointing at congressgov_bill_lookup
• Listed only when CONGRESS_MIRROR_ENABLED=true; until bun run mirror:init builds the index, it returns an empty result with a notice

congress://current _resource

• Current congress number, session dates, and chamber info, the baseline for other queries
• Cached publicly for 1 hour

congress://bill-types _resource

• The 8 bill type codes (hr, s, hjres, sjres, hconres, sconres, hres, sres) with description, chamber, and an example citation
• Static, with no upstream call; cached publicly for 24 hours

congress://member/{bioguideId} _resource

• bioguideId is one uppercase letter and 6 digits (e.g. P000197)
• Returns the member profile: name, state, party, terms, leadership, office, legislation counts

congress://bill/{congress}/{billType}/{billNumber} _resource

• congress and billNumber are positive integers; billType is one of the 8 bill type codes
• Returns bill detail: sponsor, status, policy area, committees, latest action

congress://committee/{committeeCode} _resource

• committeeCode is h/s/j followed by 3–8 lowercase alphanumeric characters (e.g. hsju00); chamber comes from the first letter
• Returns committee detail: name, chamber, subcommittees, history, legislation counts

congressgov_bill_analysis _prompt

• Arguments: congress, billType, and billNumber, all required
• Returns one user message framing a seven-part analysis, from summary to outlook, with the tools to call for each part

congressgov_legislative_research _prompt

• Arguments: topic required; congress optional, defaulting to the current congress
• With CONGRESS_MIRROR_ENABLED, the plan opens with congressgov_search_bills; without it, the prompt asks for a seed bill, member, committee, or CRS report ID, since no other tool takes a topic

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

Congress.gov-specific:

• Type-safe client for the Congress.gov REST API v3, plus a client for the Senate's LIS XML feed that backs Senate roll votes, with Voteview's published vote files as the fallback when that feed can't be read
• The Congress.gov API has no keyword search, so tools browse by congress, type, date range, chamber, state, and district; list operations page with limit 1–250 (default 20) and offset
• content on bill text, amendment text, committee reports, Record articles, and CRS reports reads a document in a characterOffset/characterLimit window (1–100,000 characters, default 25,000), fetched only from www.congress.gov under a 25 MB ceiling; bill text, committee reports, and Record articles take format text (default) or xml, a CRS report is always read as its HTML version, and an amendment is read as the HTML of its Congressional Record page. A document longer than one window (up to 16 MB) is downloaded once and its later windows are served from a 10-minute in-memory cache
• Each tool call or resource read gets 50 seconds for all of its upstream requests, retries and backoff included, whether it makes one request or chains several (a content call's metadata lookup and document fetch, a committee name resolved against the committee roster, one chamber's when chamber is set). A stalled upstream ends the call before the 60-second default timeout of MCP clients: upstream_timeout from Congress.gov, the retryable upstream_error from the Senate LIS feed and the Voteview fallback
• Optional API key from api.data.gov: DEMO_KEY allows 30 requests/hour and 50/day per IP, registered keys 5,000/hour
• Opt-in local SQLite FTS5 mirror (CONGRESS_MIRROR_ENABLED) adds keyword search over bill titles and CRS summaries

Agent-friendly output:

• Every list response carries effectiveQuery and totalCount, with a notice when nothing matched
• list refuses an identity field (member bioguideId, law lawNumber, committee committeeCode with a committee name pointed at filter, nomination nominationNumber, committee report part, and billNumber, voteNumber, reportNumber, volumeNumber) with an incompatible_identity error that names the operation to use instead
• Inputs an operation doesn't use are served with a notice naming them as ignored; a member's sponsored and cosponsored legislation and a committee's bills, reports, and nominations span every congress
• content returns offset, truncated, and nextOffset, so walking a multi-megabyte bill never skips or repeats a character
• Typed failures (document_unavailable, format_unavailable, document_fetch_failed, document_too_large, offset_past_end, unsupported_filter, not_found, rate_limited, invalid_request, api_key_rejected, upstream_error, upstream_timeout), each with a recovery hint

Getting started

Connect to the hosted instance:

claude mcp add --transport http congressgov-mcp-server https://congressgov.caseyjhand.com/mcp

Or run it locally:

claude mcp add congressgov-mcp-server -- npx -y @cyanheads/congressgov-mcp-server

For other clients, add this to the MCP config file:

{
  "mcpServers": {
    "congressgov-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/congressgov-mcp-server"]
    }
  }
}

Optional: set CONGRESS_API_KEY to a free api.data.gov key for 5,000 requests/hour instead of the demo key's 30/hour and 50/day per IP. For Docker or a source build, see Running the server.

Configuration

See .env.example for the full list of optional overrides.

Running the server

Requires Bun v1.4.0 or higher (or Node.js v24+).

git clone https://github.com/cyanheads/congressgov-mcp-server.git
cd congressgov-mcp-server && bun install
cp .env.example .env
# Optionally set CONGRESS_API_KEY and the mirror variables in .env.

Local development

• Build and run the production version:

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

• Build the bill search mirror from this checkout (with CONGRESS_MIRROR_ENABLED=true):

  bun run mirror:init      # full build
  bun run mirror:refresh   # incremental refresh
  bun run mirror:verify    # readiness and integrity check
  

  The mirror CLI requires this checkout or the Docker image's path mapping; an npm installation cannot run these scripts.

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker run --rm -e CONGRESS_API_KEY=your-api-key -p 3010:3010 ghcr.io/cyanheads/congressgov-mcp-server:latest

The image defaults to HTTP transport, stateless session mode, and logs to /var/log/congressgov-mcp-server. For stdio, use docker run -i --rm -e MCP_TRANSPORT_TYPE=stdio ghcr.io/cyanheads/congressgov-mcp-server:latest. To build locally, run docker build -t congressgov-mcp-server .; OpenTelemetry peer dependencies are installed by default, with --build-arg OTEL_ENABLED=false to omit them. The image carries the mirror scripts, so docker exec <container> bun run mirror:init builds the index in place.

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 request-scoped logging, ctx.state for tenant-scoped storage
• All tools are read-only, with readOnlyHint: true and idempotentHint: true annotations
• Wrap external API calls: validate raw → normalize to a domain type → return the output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.