civic-awareness-mcp

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
civic-federal-mcp	Congress.gov + OpenFEC	US federal	npx civic-federal-mcp
civic-state-mcp	OpenStates	50 states + DC	npx civic-state-mcp

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.

Tools

civic-federal-mcp (9 tools)

Tool	Kind	What it answers
recent_bills	feed	Bills introduced or acted on in the last N days (Congress.gov)
recent_votes	feed	Roll-call votes in the last N days, yea/nay/present tallies
recent_contributions	feed	Federal campaign contributions in a date window (OpenFEC)
search_civic_documents	search	Title search across cached federal bills, votes, contributions
search_entities	entity	Name search across Members of Congress + FEC candidates/committees
get_entity	entity	Entity detail + role history + recent documents
resolve_person	entity	Disambiguate a name into one or more Person entity IDs
entity_connections	entity	Co-occurrence graph via bills, votes, contributions (depth 1–2)
get_vote	detail	Full roll-call vote with per-legislator positions

civic-state-mcp (8 tools)

Tool	Kind	What it answers
recent_bills	feed	Bills by jurisdiction; filters for sponsor, subject, classification, session, dates
recent_votes	feed	Roll-call votes in the last N days, chamber + tally (OpenStates, per jurisdiction)
get_bill	detail	Full bill detail: actions, versions, sponsors, subjects
search_civic_documents	search	Title search across cached state bills
search_entities	entity	Name search across state legislators (OpenStates)
get_entity	entity	Entity detail + role history + recent documents
resolve_person	entity	Disambiguate a name into one or more Person entity IDs
entity_connections	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:state

For development (no build step):

npm run dev:federal
npm run dev:state

Data 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=1

To prune stale fetch-log rows (recommended monthly):

npm run evict-fetch-log

Development

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 --write

Claude 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
API_DATA_GOV_KEY	federal	api.data.gov key (Congress.gov + OpenFEC)
OPENSTATES_API_KEY	state	OpenStates v3 API key
CIVIC_FEDERAL_DB_PATH	federal	SQLite path (default ./data/federal.db)
CIVIC_STATE_DB_PATH	state	SQLite path (default ./data/state.db)
CIVIC_AWARENESS_DAILY_BUDGET	both	Optional daily API spend cap (unused by default)
LOG_LEVEL	both	debug / info / warn / error (default info, JSON to stderr)

CI

Four workflows in .github/workflows/:

• ci.yml — format, lint, typecheck, tests, build, MCP stdio smoke. Matrix on Node 22/24. Runs on push to main and 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 via workflow_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-After honoured
• Zod-validated inputs; parameterized SQLite queries
• No contributor PII in responses

License

MIT — see LICENSE.