Oravan MCP server
Commit Nov 16, 2026Provides nonpartisan U.S. Congress data including bill decodes, representative lookups, and bilingual English/Spanish summaries for AI assistants.
Also known as cm2489/oravan
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.1.0
- Last commit
- Nov 16, 2026
- License
- AGPL-3.0
What is Oravan MCP?
Oravan provides nonpartisan U.S. Congress data including bill decodes, representative lookups, and bilingual English/Spanish summaries for AI assistants.
Summary generated from the project's README
About Oravan MCP server
Oravan provides nonpartisan civic data to help users understand the activities of the United States Congress. It is designed for AI assistants and agents to access decoded bill information, representative lookups, and bilingual summaries in English and Spanish. The service functions as both a remote MCP server via a streamable HTTP endpoint and a local implementation using stdio.
Developers can connect to the remote server without any accounts or credentials, though it is subject to rate limits. The local version can be run using npm and npx. The system includes five specific tools: lookup_representatives, get_bill, search_bills, whats_moving, and get_representative. Every response includes a citation envelope containing the source, freshness, and an AI-content label. This infrastructure focuses on privacy by avoiding server-side user data and utilizing static JSON files for rapid, resilient access to legislative information.
What you can do with it
- 1Identify federal representativesAn AI agent can find specific members of Congress or identify representatives based on a user's location.
- 2Analyze active legislationA developer can use the server to retrieve plain language summaries of current bills in either English or Spanish.
- 3Monitor legislative trendsAn assistant can query the server to discover which legislative topics are currently gaining momentum.
- 4Retrieve detailed bill dataAn AI client can fetch specific information regarding a particular piece of legislation using its unique identifier.
Written from the project's README. Every use case is checked against a quote from it.
How to install Oravan MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Oravan MCP in Claude Code
$ claude mcp add --transport http oravan https://oravan.org/api/mcp/mcpInstall Oravan MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"oravan": {
"url": "https://oravan.org/api/mcp/mcp"
}
}
}Install Oravan MCP in VS Code
.vscode/mcp.json
{
"servers": {
"oravan": {
"type": "http",
"url": "https://oravan.org/api/mcp/mcp"
}
}
}Install Oravan MCP in VS Code CLI
$ code --add-mcp '{"name":"oravan","type":"http","url":"https://oravan.org/api/mcp/mcp"}'Install Oravan MCP in Codex
$ codex mcp add oravan --url https://oravan.org/api/mcp/mcpInstall Oravan MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.oravan] url = "https://oravan.org/api/mcp/mcp"
Install Oravan MCP in Gemini CLI
$ gemini mcp add -s user --transport http oravan https://oravan.org/api/mcp/mcpInstall Oravan MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"oravan": {
"url": "https://oravan.org/api/mcp/mcp",
"type": "http"
}
}
}Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablecm2489/oravan is public and reachablegithub.com/cm2489/oravan ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)AGPL-3.0spdx.org/licenses/AGPL-3.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-14github.com/cm2489/oravan ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeinitialize answered with protocol 2025-06-18 in 3544 msPass
README
View on GitHubOravan
Your line to Congress · Tu línea con el Congreso
Oravan is free, nonpartisan civic infrastructure: find your federal representatives, understand active bills in plain language (English and Spanish), get a 30-second call script, and make the call — in under 5 minutes, with no account.
MCP server
This repository also implements a remote MCP (Model Context Protocol) server — the same decoded corpus and lookups, exposed for AI assistants and agents:
- Endpoint (Streamable HTTP):
https://oravan.org/api/mcp/mcp— keyless, read-only, rate-limited; no account or credentials required - Local/stdio:
npm cithennpx tsx scripts/mcp-stdio.mjs— the same 5 tools over stdio, zero env vars/secrets required - Implementation:
app/api/mcp/[transport]/route.ts(built onmcp-handler+@modelcontextprotocol/sdk), tool definitions shared with the stdio entry vialib/core/mcp-tools.ts, pure data layer inlib/core/ - Five tools:
lookup_representatives,get_bill,search_bills,whats_moving,get_representative— every response carries a citation envelope (source, as-of freshness, AI-content label, license) in English or Spanish - Official MCP Registry: published as
org.oravan/mcp(server.jsonat the repo root, schema-validated in CI byscripts/check-server-json.mjs) - Docs: oravan.org/mcp (tool reference, client config, privacy posture) · docs/mcp-server-readme.md
Design principles
-
Zero accounts. ZIP code, interests, and call history live in
localStorageon the visitor's device. No server-side user data exists — nothing to breach, leak, or subpoena. This is the core privacy posture for at-risk users, not a missing feature. -
Static-first. Bills, legislators, district offices, and ZIP→district mappings are static JSON in
data/, baked into ~7,500 statically generated pages (7,566 in the 2026-09-24 build, including a page for every member of Congress and a daily brief). Fast, nearly free to host, resilient under load. The server endpoints are/api/script(AI call-script generation, cached per bill + stance + language + content version in a shared store, IP rate-limited),/api/reps(pure lookup),/api/district(stateless split-ZIP address refinement: proxies the Census geocoder so the visitor's IP never reaches census.gov; the address is never stored or logged),/api/mcp(the MCP server below),/api/brand(an AI theme suggestion for a partner's site, used by the/embedsconfigurator, which is hidden until embeds come back),/api/stripe/webhook(partner-plan provisioning; refuses with 503 until its signing secret is set),/api/tenant/impressions(a partner reads its own embed impression counts), and/embed/portrait/[bioguide](a same-origin portrait proxy for the embeds). Two page routes render per request —/reps(it reads the ZIP from the URL) and/nominations/[slug]— andtests/static-rendering.spec.tsnames them with the reason. -
Bilingual as a first-class feature. Full EN/ES UI via
next-intl; scripts are generated in the user's language. -
Truth first; the call is the natural next step. Oravan leads as an unbiased, plain-words account of what Congress is actually doing — understanding is the front door, never an assignment. The call apparatus stays the differentiator (voicemail legitimized, offices tally it identically; after-hours calling encouraged; district offices listed alongside DC; outcomes — spoke / voicemail / couldn't reach — logged locally on the device), and every decoded answer on a decision still open keeps a completed call script within two interactions; once the decision is over — a law, a rejected vote — the page shows the outcome and how your members voted instead. Demoted, never buried. (Amended 2026-07-26; previously "The call moment is the product." Scoped to a decision still open on 2026-09-28. Enforced by the three named invariants in
tests/funnel.spec.ts.) -
Honest about AI. Every generated summary and script is labeled at first contact, and nothing publishes unless the automated gates pass: both languages present, the official record attached, and a schema check on every decode — a decode that comes back missing a required field is discarded rather than stored half-written, and
scripts/verify-sync.mjsre-checks the whole corpus and fails the nightly run before it is allowed to commit anything. (Amended 2026-08-12: one check left that file and now runs AFTER the commit — the cursor-age ceiling inscripts/check-cursor-age.mjs. It is a progress signal, not a corpus one: a stalled cursor means we are behind, and failing it before the commit made a stalled night throw away a night of already-paid decodes. Every corpus check named here is unchanged and still runs before anything is committed. Seedocs/constitution-log.md#cursor-age-2026-08-12.) Nonpartisan wording is a drafting instruction to the model on bill decodes and an enforced vocabulary lint on Big Questions (lib/moments-gate.mjs) — the two are not the same guarantee, and the copy never blurs them. The nightly decode path has no human step and the product never claims one; the one review it does claim is real: a caller reads, and can edit, the call script before dialing. (Amended 2026-08-06; previously "labeled, editable, and reviewed by the human before any call." See the 2026-07-25 amendment indocs/constitution-log.md, which this line should have followed and did not.)AI content is labeled at first contact, and a call script is read — and editable — by the caller before it drives a call. That last clause is scoped to call scripts on purpose: decodes and Moment update summaries publish behind automated gates with no human step, so the label is the whole disclosure there. The label sits with the content, above the fold — never in a footnote. (Moved here from
DESIGN.mdon 2026-09-27, when that file was retired.) -
Accessible by default. Semantic landmarks, skip link, visible focus,
prefers-reduced-motion, 44px+ touch targets, AA contrast.
Data sources
| File | Source | Refresh |
|---|---|---|
data/bills.json + data/bills-es.json |
Decoded bill corpus (Congress.gov bills + AI plain-language summaries, English and Spanish) | Nightly sync (scripts/sync-bills.mjs via sync-bills.yml): statuses refresh freely; new bills are decode-before-publish, entering the corpus only once their EN and ES summaries exist. Each record also stores which text version its decode was produced from, and a bill whose text Congress replaces — an amendment in committee changes the document without changing the title or the status — is re-read from the new text on a later nightly, at most 10 a night (REDECODE_MAX_PER_NIGHT, a cost ceiling; the backlog of older records drains a few a night, urgent bills first) |
data/legislators.json |
unitedstates/congress-legislators (public domain) + district offices | scripts/process-data.py |
data/zip-districts.json |
OpenSourceActivismTech/us_zipcodes_congress | same |
data/vacancies.json |
Derived, not fetched: scripts/vacancy_diff.py diffs seat sets against the currently-committed data every run, so a departed member with no successor surfaces as an explicit vacancy (reps page, /api/reps, MCP lookup_representatives) instead of silently disappearing or being backfilled from a stale term record |
scripts/process-data.py (same run as legislators.json) |
data/special-elections.json |
Each vacant seat's special-election dates exactly as the Federal Election Commission's election-dates API lists them (date + the FEC's election-type code), with the day they were checked. No row means an empty list, never a guessed date; no member-elect is recorded, because no official machine-readable source names one before the oath. Shown on the vacant-seat card on /reps and the seat's own page |
scripts/sync-special-elections.mjs, weekly via refresh-legislators.yml right after the vacancy diff (api.data.gov's public DEMO_KEY, no secret; a failed request keeps the last entry and its old checked date) |
data/redistricting-watch.json |
Human-authored (status/note) for the 10 states with contested-or-recent 2025–26 mid-decade map changes; rdh_lastmod is a tripwire baseline against the Redistricting Data Hub's own state-page sitemap — see docs/solutions/two-clock-district-boundaries.md |
scripts/check-redistricting-watch.mjs, weekly via refresh-legislators.yml; on change it comments on ONE standing, pinned redistricting-watch issue whose body is a rewritten 10-state status board (it used to open one issue per changed state — ten accumulated in six weeks, eight of them from a single RDH site-wide republish), never auto-updates status/note |
data/nominations.json |
Civilian Senate nominations (PNs) of the 119th Congress — Congress.gov's own citation, description sentence, and latest action, plus a status derived from that action text by lib/nomination-status.mjs's rule table. No AI touches this file — Oravan does not decode or rewrite a nomination, because Congress.gov's description is already one plain English sentence, so /nominations/[slug] renders the Senate's own record verbatim and says so on the page. The one piece of AI is the call script, labeled where it is generated. A nomination can be a Big Question's vehicle; the card, the page, and the call are live. It stays English on /es like the coverage titles below (see Known v1 caveats). Military promotion lists are excluded (no description, no nameable nominee). No MCP tool exposes nominations yet. |
scripts/sync-nominations.mjs (nightly, one free request; gated by scripts/check-nominations.mjs) |
data/coverage.json |
Real news articles about top-band bills via TheNewsAPI, AI-relevance-filtered (Haiku) | scripts/sync-coverage.mjs (nightly, gated on NEWS_API_KEY) |
data/media-bias.json |
Outlet political-lean ratings by AllSides, used under CC BY-NC with attribution | Vendored snapshot |
Portraits are served from the public-domain unitedstates/images project.
Solved pipeline incidents (root cause + the CI gates that prevent recurrence) are documented in docs/solutions/.
The "Read" section (outlet-bias coverage)
Each top bill's page shows real third-party articles about it, labeled by the outlet's political lean (Left / Center / Right) — reusing AllSides' publication-level ratings, never a Oravan-invented one. Oravan takes no stance and authors no partisan text: AI is used only behind the scenes — generating each bill's news-search terms (press-style names and a subject query) and a cheap relevance gate (is this article about this bill?) — and authors nothing displayed. The ingestion runs nightly in CI and bakes results to JSON, so the site still makes zero runtime third-party calls. Without NEWS_API_KEY the sync is a no-op and the section renders nothing; a small hand-built real sample (data/coverage.json) keeps it demoable. Lean is shown by text label + position only — never party colors (a hard rule; see CLAUDE.md, rule 3).
Develop
npm install
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env.local # script generation + decode/relevance
echo "NEWS_API_KEY=..." >> .env.local # optional; enables the "Read" coverage sync
npm run dev
npm run build statically generates every bill page in both locales.
Known v1 caveats
- ZIP→district mapping is ZCTA-based; a split ZIP shows all candidate districts by default (senators are unaffected). Entering a street address — optional, sent once by POST, never stored or logged — narrows it to the actual district via a server-proxied Census-geocoder lookup; the all-candidates view remains the graceful fallback whenever the geocoder can't help. The geocoder request pins the "119th Congressional Districts" layer, which needs a bump when the Census rolls the vintage to the 120th.
- The script cache and the rate limits live in shared Upstash stores (
lib/scriptcache.ts,lib/ratelimit.ts). When those stores are not configured — local dev, CI, previews — or a request to one fails, both fall back to per-instance memory rather than fail the request. - New bills can lag behind Congress.gov: the nightly sync decodes at most
MAX_NEW_DECODESnew bills per run (cost ceiling), so after a missed window the corpus catches up over several nights (decode-before-publish; the backlog drains oldest-first). - "Read" coverage exists only for top-band bills (the long tail shows nothing); the ES locale shows the same English articles with localized chrome; outlets absent from
data/media-bias.jsonappear without a lean chip.
License
- Code: GNU AGPL-3.0. You may use, modify, and run this code — including as a network service — provided modified versions you operate or distribute remain open under the same license. Embedding Oravan's hosted widgets on your site via the loader/script tag does not subject your site to the AGPL; that's use of our service, not distribution of this code.
- Not licensed: the Oravan name, logo, and brand assets (
assets/brand/, app icons). All rights reserved — forks must use their own identity. - Content: underlying legislative data is U.S. government work (public domain). AI-generated decodes and summaries are licensed CC BY 4.0, exactly as declared in the MCP citation envelope and on the citations page.
Oravan MCP questions
How do I add Oravan MCP to Claude Code?
Run claude mcp add --transport http oravan https://oravan.org/api/mcp/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Oravan MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does using Oravan require an account?
No, the service is designed to be used with no account or credentials required.
Is the data available in Spanish?
Yes, the server provides bilingual support for both English and Spanish.
How is user privacy handled?
The system follows a zero-account design where user data like ZIP codes and interests are stored only in the visitor's local device storage.