Skip to main content
Glama
civic-awareness-mcp

civic-awareness-mcp

by julianken

Civic Awareness MCP

Two MCP servers for US civic data — one for Congress + federal campaign finance, one for 50-state legislatures.

License: MIT Node 22+ Nightly drift

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.

Related MCP server: LegiScan MCP Server

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

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.

Available Tools

8 tools
entity_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

    A3.8/5.0

    Scored across 8 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case (e.g., get_bill, search_entities, recent_votes). No naming style conflicts.

    Tool Count5/5

    8 tools cover the domain of state legislative data without being too few or excessive. Each tool serves a clear function in the workflow.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Provides 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.
      10
      13 npm
      12
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables querying U.S. legislative data from Congress.gov API using MCP resources for direct lookups and tools for searching and retrieving related data.
      8
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables querying legislative data from the LegiScan API, including bills and votes, via natural language through an MCP gateway.
      137 npm
      MIT