CongressMCP

Live U.S. Congressional data for any MCP client — Claude Code, ChatGPT, Copilot, Codex, Cursor, OpenCode, Gemini CLI, Grok Build, and more.

Bills, full bill text, votes, members, committees, hearings, nominations, and the Congressional Record — queried in natural language through the Model Context Protocol. Runs locally on your machine against the free Congress.gov and GovInfo APIs. No account, no hosted service, no telemetry.

Quick Start

1. Get a free Congress.gov API key

Sign up at api.congress.gov/sign-up — takes 30 seconds. The same key also works for GovInfo (full bill text).

2. Install uv

CongressMCP is published on PyPI and launched with uvx, which ships with uv:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

(brew install uv, winget install astral-sh.uv, and pipx install uv also work.) Prefer pip? pip install congressmcp gives you a congressmcp command you can use in place of uvx congressmcp below.

3. Connect your client

Every client needs the same three facts: command uvx, args ["congressmcp"], env CONGRESS_API_KEY. Clients are listed roughly by how many professional developers use them today (JetBrains Developer Ecosystem survey, mid-2026, then Pragmatic Engineer’s 2026 tooling survey), so the one you want is probably near the top:

Anything not listed that speaks MCP over stdio will work with the same three values.

4. Start asking questions

“Find recent climate change bills in the 119th Congress” “Where in the FY2026 NDAA is the Coast Guard’s icebreaker funding?” “How did senators from California vote on the latest defense bill?” “Who are the members of the Senate Judiciary Committee?” “What’s the latest action on H.R. 1234?”

Remote / HTTP mode

For clients that connect by URL (ChatGPT, Claude.ai connectors, Open WebUI, or several users sharing one install), run the server over Streamable HTTP:

CONGRESS_API_KEY=your-key congressmcp --transport streamable-http --host 0.0.0.0 --port 8000
# MCP endpoint: http://:8000/mcp

CongressMCP has no built-in authentication. The server is designed to run on your own machine. If you expose it beyond localhost, put it behind something that does authenticate — a reverse proxy with an access policy, an HTTPS tunnel with an allow-list, or a VPN — and remember that anyone who can reach it is spending your Congress.gov quota. ChatGPT and Claude.ai additionally require HTTPS on a publicly resolvable hostname.

Tools

7 toolsets, 90+ operations covering the Congress.gov API, plus full-text bill retrieval from GovInfo:

search_committees and search_summaries take an optional keywords argument — omit it to browse/list (committees can also be filtered by chamber/committee_type).

Full Bill Text Search

What changed: instead of proxying API responses, CongressMCP fetches the full Bill DTD XML from GovInfo, parses it locally, builds a segment-level SQLite FTS5 index per bill version, and returns targeted, addressable bill sections instead of raw multi-megabyte XML or whole rendered bill pages. Indexes are persisted on disk and reused across calls and restarts.

No new API key is needed. GovInfo and Congress.gov both sit behind api.data.gov, so CongressMCP reuses your existing CONGRESS_API_KEY for both; set GOVINFO_API_KEY only if you want a separate GovInfo key. (People assume a second key is required. It is not.)

Where data lives. One SQLite file per bill version (.v.db, e.g. BILLS-119s1071enr.v1.db) under packages/ in the cache root, plus a small manifest.db index. The cache root is CONGRESSMCP_CACHE_DIR if set, otherwise the platform default:

How much disk. Capped at 500 MB by default (CONGRESSMCP_CACHE_MAX_BYTES, bytes), enforced by least-recently-used eviction after every index write. An NDAA-scale enrolled bill (S.1071/119, 1,448 indexed units) builds an 11 MB index; most bills are far smaller. Inspect or empty the cache from the command line — it is deliberately not an MCP tool:

congressmcp cache info          # path, cap, total bytes, one line per package
congressmcp cache clear --yes   # remove every package file and the manifest

Deleting the cache directory by hand is also safe at any time; the files are a cache, not a store.

First-call latency — measured, not estimated. Cold (nothing cached) on S.1071/119: 4.1–6.8 s end to end across runs, of which congress.gov version resolution + the GovInfo package summary took 3.0–3.4 s, the XML download 1.1–2.3 s, parse 0.75 s, and the FTS5 build 0.31 s — the network legs are the slow and variable part, and they are the part the cache removes. Warm (index and version resolution cached): 30–60 ms, no network. Every response carries a timing block (resolve_ms, download_ms, parse_ms, index_ms, search_ms, total_ms; a leg is null when it did not run) and a cache block (index_hit, version_hit), so you can see which case you got. Client-timeout implication: set your MCP client’s per-call timeout to at least 30 s; a cold NDAA-scale call under a slow network can exceed a 10 s default and the partial work is not lost — the next call is warm.

Offline behavior. A version you have fetched explicitly (version="enr") is fully queryable offline for as long as it stays in the cache; explicitly cached versions are re-checked against GovInfo’s lastModified only every CONGRESSMCP_REVALIDATE_DAYS (30) and rebuilt if the package was reissued. With version omitted, the “latest version” answer is cached for CONGRESSMCP_VERSION_TTL (86400 s = 1 day; version_resolution: "cached"); past the TTL it is re-resolved, and if the network is unavailable the last answer is served best-effort and labelled version_resolution: "cached_offline" with the resolution timestamp and a note that a newer version may exist. If nothing is cached and the network is down you get version_resolution_unavailable, listing the versions of that bill that are cached so you can pin one.

Network egress. Exactly two hosts: api.congress.gov (bill and text-version metadata) and api.govinfo.gov (bill content). Both independently rate-limited per api.data.gov (20,000/h and 36,000/h), so indexing cannot starve the other tools.

Setting CONGRESSMCP_CACHE_ENABLED=false turns all of this off: every call re-downloads, re-parses and re-indexes the full document in memory — NDAA-scale latency, every time. It exists for diagnosis, not for normal use.

The search response distinguishes matches in operative, quoted, and header segments. If quoted appears in match_contexts, the hit may include language the bill is removing, even when operative also appears; retrieve the section before drawing conclusions about strike-and-insert language.

Each hit also carries matched_queries — the subset of your queries that produced it. Read it before reasoning about retrieval behavior: in a multi-query call it attributes every hit to its originating query, so an unexpected result is explained by the field, not by guessing at tokenizer internals.

amends resolves U.S. Code citations only (the longhand Section {sec} of title {title}, United States Code form and the shorthand {title} U.S.C. {sec} form when an amendatory verb follows). It does not resolve named Acts, including the Internal Revenue Code cited by bare section number — so most Title VII tax units report is_amendatory: true with amends: []. Use is_amendatory and match_contexts to identify amendatory text; amends is a convenience, not a completeness guarantee.

Running from source

git clone https://github.com/amurshak/congressMCP
cd congressMCP
pip install -e .

# stdio (default — for MCP clients)
CONGRESS_API_KEY=your-key congressmcp

# HTTP (for self-hosting / remote access)
CONGRESS_API_KEY=your-key congressmcp --transport streamable-http --port 8000

Point a client at a source checkout by using "command": "congressmcp" (with the venv activated or its bin/ on PATH) or "command": "/path/to/venv/bin/congressmcp" in place of uvx.

Configuration

Cache CLI (the cache is administered from the command line, never via an MCP tool):

congressmcp cache info          # exit 0
congressmcp cache clear --yes   # exit 0; without --yes in a non-interactive shell it refuses with exit 1

Troubleshooting

• “command not found: uvx” in a GUI client (Claude Desktop, Zed, LM Studio, JetBrains): use the absolute path from which uvx (macOS/Linux) or where uvx (Windows) as the command.
• Windows: if a client can’t spawn uvx directly, use "command": "cmd", "args": ["/c", "uvx", "congressmcp"].
• First start is slow: uvx downloads and caches the package on first run; subsequent starts are fast. Pin a version with uvx [email protected] if you want reproducibility.
• 401 / 403 from the API: the key is missing or wrong. Confirm it works with curl "https://api.congress.gov/v3/bill?api_key=YOUR_KEY&limit=1".
• Tools missing in the client: most clients need a restart or an explicit MCP reload after editing config.

Contributing

See CONTRIBUTING.md for the full process: fork, branch, code style, commit conventions, and how to submit a pull request.

License

Sustainable Use License

---

Built for government transparency and accessible civic data.