# Civic Awareness Mcp > An MCP server for US federal and state legislative data. Pulls from OpenStates and Congress.gov with a cross-jurisdiction entity graph. - **Type:** MCP server - **Install:** `agentstack add mcp-julianken-civic-awareness-mcp` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [julianken](https://agentstack.voostack.com/s/julianken) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [julianken](https://github.com/julianken) - **Source:** https://github.com/julianken/civic-awareness-mcp ## Install ```sh agentstack add mcp-julianken-civic-awareness-mcp ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Civic Awareness MCP Two [MCP](https://modelcontextprotocol.io) servers for US civic data — one for Congress + federal campaign finance, one for 50-state legislatures. [](./LICENSE) [](https://github.com/julianken/civic-awareness-mcp/actions/workflows/nightly-drift.yml) ## 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](https://api.data.gov/signup/) (covers Congress.gov + OpenFEC), [OpenStates](https://openstates.org/accounts/signup/) — all free tier ### Build + run ```bash 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): ```bash npm run dev:federal npm run dev:state ``` ### Data hydration The server fetches data automatically on cache miss. For bulk pre-population: ```bash # 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): ```bash npm run evict-fetch-log ``` ### Development ```bash 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`: ```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`](./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`](./LICENSE). ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [julianken](https://github.com/julianken) - **Source:** [julianken/civic-awareness-mcp](https://github.com/julianken/civic-awareness-mcp) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-julianken-civic-awareness-mcp - Seller: https://agentstack.voostack.com/s/julianken - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.