civic-awareness-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@civic-awareness-mcp Show me recent bills on healthcare in Congress"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Civic Awareness MCP
Two MCP servers for US civic data — one for Congress + federal campaign finance, one for 50-state legislatures.
Servers
Server | Source | Jurisdictions | Package |
| Congress.gov + OpenFEC | US federal |
|
| OpenStates | 50 states + DC |
|
Each server reads/writes-through to a local SQLite store as a TTL cache. Every response includes a sources: { name, url }[] array for provenance. No tool synthesizes summaries — that is the LLM's job.
Related MCP server: LegiScan MCP Server
Tools
civic-federal-mcp (9 tools)
Tool | Kind | What it answers |
| feed | Bills introduced or acted on in the last N days (Congress.gov) |
| feed | Roll-call votes in the last N days, yea/nay/present tallies |
| feed | Federal campaign contributions in a date window (OpenFEC) |
| search | Title search across cached federal bills, votes, contributions |
| entity | Name search across Members of Congress + FEC candidates/committees |
| entity | Entity detail + role history + recent documents |
| entity | Disambiguate a name into one or more Person entity IDs |
| entity | Co-occurrence graph via bills, votes, contributions (depth 1–2) |
| detail | Full roll-call vote with per-legislator positions |
civic-state-mcp (8 tools)
Tool | Kind | What it answers |
| feed | Bills by jurisdiction; filters for sponsor, subject, classification, session, dates |
| feed | Roll-call votes in the last N days, chamber + tally (OpenStates, per jurisdiction) |
| detail | Full bill detail: actions, versions, sponsors, subjects |
| search | Title search across cached state bills |
| entity | Name search across state legislators (OpenStates) |
| entity | Entity detail + role history + recent documents |
| entity | Disambiguate a name into one or more Person entity IDs |
| entity | Co-occurrence graph via shared sponsored bills (depth 1–2) |
Installation
Prerequisites
Node.js ≥ 22
API keys: api.data.gov (covers Congress.gov + OpenFEC), OpenStates — all free tier
Build + run
npm install
npm run build
# federal server
npm run bootstrap:federal
npm run start:federal
# state server
npm run bootstrap:state
npm run start:stateFor development (no build step):
npm run dev:federal
npm run dev:stateData hydration
The server fetches data automatically on cache miss. For bulk pre-population:
# federal
npm run refresh:federal -- --source=congress --max-pages=1
npm run refresh:federal -- --source=openfec --max-pages=1
# state (one jurisdiction)
npm run refresh:state -- --source=openstates --jurisdictions=tx --max-pages=1To prune stale fetch-log rows (recommended monthly):
npm run evict-fetch-logDevelopment
npm test # mocked unit + integration suite (MSW)
npm run test:watch # rerun on change
npm run test:drift # live-API drift tests (requires .env.local)
npm run typecheck # tsc --noEmit
npm run lint # eslint
npm run format # prettier --writeClaude Desktop config
To run both servers locally, add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"civic-federal-mcp": {
"command": "node",
"args": ["/absolute/path/to/civic-awareness-mcp/dist/federal/index.js"],
"env": {
"API_DATA_GOV_KEY": "your-key",
"CIVIC_FEDERAL_DB_PATH": "/absolute/path/to/federal.db"
}
},
"civic-state-mcp": {
"command": "node",
"args": ["/absolute/path/to/civic-awareness-mcp/dist/state/index.js"],
"env": {
"OPENSTATES_API_KEY": "your-key",
"CIVIC_STATE_DB_PATH": "/absolute/path/to/state.db"
}
}
}
}Environment variables
Variable | Server | Description |
| federal | api.data.gov key (Congress.gov + OpenFEC) |
| state | OpenStates v3 API key |
| federal | SQLite path (default |
| state | SQLite path (default |
| both | Optional daily API spend cap (unused by default) |
| both |
|
CI
Four workflows in .github/workflows/:
ci.yml— format, lint, typecheck, tests, build, MCP stdio smoke. Matrix on Node 22/24. Runs on push tomainand on every PR.codeql.yml— CodeQL static analysis. Runs on push/PR/weekly.scorecard.yml— OpenSSF Scorecard. Runs on push/weekly.nightly-drift.yml— live-API shape checks against OpenStates, Congress.gov, OpenFEC. Runs daily at 09:00 UTC and on-demand viaworkflow_dispatch.
The drift workflow requires repo secrets OPENSTATES_API_KEY and API_DATA_GOV_KEY (separate from user keys — those are configured locally via .env.local).
Security
See SECURITY.md. Highlights:
Never writes to upstream APIs
All sources are sanctioned free-tier APIs with documented rate limits
Rate-limited fetch with per-host token bucket;
Retry-AfterhonouredZod-validated inputs; parameterized SQLite queries
No contributor PII in responses
License
MIT — see LICENSE.
Available Tools
8 toolsentity_connectionsA
Given an entity ID, return co-occurrence edges to other entities via shared state bills. Supports depth=1 (direct) or depth=2 (through one hop). Edges are capped at 100 and sorted by co_occurrence_count descending.
Inputs: id (required), depth, min_co_occurrences.
get_billA
Fetch full detail for a single state bill including actions, versions, sponsors, and subjects. Requires jurisdiction, session, and identifier.
Inputs: session (required), identifier (required), jurisdiction (required).
get_entityA
Fetch a single entity by ID with recent related documents. For state Persons, returns the cross-jurisdiction roles[] history.
Inputs: id (required).
recent_billsA
List U.S. state legislative bills from OpenStates. Defaults to the last days (default 7) of recently-updated bills. Optional filters: chamber, session, sponsor_entity_id (civic entity UUID, resolved to OpenStates OCD id), classification, subject, introduced_since/until, updated_since/until, sort. Any explicit date range overrides days. Pass a jurisdiction like 'us-tx' or 'us-ca'; '*' queries all cached jurisdictions locally. Useful for 'what did this legislator introduce' and 'recent bills on ' queries.
Inputs: jurisdiction (required), days, sort, limit, +9 more.
recent_votesA
List recent roll-call votes from state legislatures via OpenStates. Pass a jurisdiction like 'us-tx' or 'us-ca'. Votes are sourced from recently-updated bills with embedded vote data. Use '*' to query all cached jurisdictions locally.
Inputs: jurisdiction (required), days, limit, chamber, +1 more.
resolve_personB
Disambiguate a person by name across state legislators. Returns all matching Person entities with confidence tiers. Supply jurisdiction_hint to trigger upstream OpenStates hydration.
Inputs: name (required), context, role_hint, jurisdiction_hint.
search_civic_documentsA
Search state civic documents (bills) by title. Optionally filter by jurisdiction, kind, source, or date range.
Inputs: q (required), to, from, kinds, +3 more.
search_entitiesA
Search for people or organizations by name across state legislatures (OpenStates). Pass a jurisdiction to trigger upstream hydration.
Inputs: q (required), kind, limit, had_role, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools have distinct purposes (bill detail, entity lookup, recent bills, votes, search, connections). However, search_civic_documents and recent_bills both retrieve bills, though via different access patterns (search vs. listing), causing minor overlap.
All tool names follow a consistent verb_noun pattern using snake_case (e.g., get_bill, search_entities, recent_votes). No naming style conflicts.
8 tools cover the domain of state legislative data without being too few or excessive. Each tool serves a clear function in the workflow.
Core operations for browsing state bills, entities, votes, and connections are present. Missing features like jurisdiction listing or bill text retrieval are minor gaps that don't break typical workflows.
Maintenance
Related MCP Connectors
Federal and 50-state legislative data for AI: bills, text, votes, members, and committees.
U.S. federal policy data — bills, Congress members, voting records, and civic info.
U.S. campaign finance, congressional votes, bill text X-ray, and primary-source civic receipts.
1Search bills and speaker-attributed hearing transcripts across all 50 US state legislatures.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables access to comprehensive U.S. legislative and governmental data from GovInfo.gov and Congress.gov APIs, including bills, Congressional records, Federal Register documents, member information, and committee activities.1MIT
- AlicenseAqualityCmaintenanceProvides access to legislative data from all 50 US states through the LegiScan API, enabling comprehensive search and retrieval of bills, votes, legislators, and legislative session information.1013 npm12MIT
- AlicenseNot gradedqualityDmaintenanceEnables querying U.S. legislative data from Congress.gov API using MCP resources for direct lookups and tools for searching and retrieving related data.8MIT
- AlicenseNot gradedqualityCmaintenanceEnables querying legislative data from the LegiScan API, including bills and votes, via natural language through an MCP gateway.137 npmMIT