Skip to main content
Glama
julianken

civic-awareness-mcp

by julianken
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

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.

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.

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/julianken/civic-awareness-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server