io.github.cyanheads/openfec-mcp-server

Official

by cyanheads · TypeScript

Access FEC campaign finance data. Query data about candidates, money trails, and election filings.

Access FEC campaign finance records, candidate information, and election filing data.

Topics

campaign-financeelectionsfecmcpmcp-servermodel-context-protocolopenfecfederal-electionspolitical-contributionsai-agenttypescriptcyanheads

README.md13 KBView on GitHub

<div align="center"> <h1>@cyanheads/openfec-mcp-server</h1> <p><b>Access FEC campaign finance data through MCP. Query data about candidates, money trails, and election filings. STDIO & Streamable HTTP.</b> <div>9 Tools • 5 Resources • 2 Prompts</div> </p> </div> <div align="center">

</div> <div align="center">

Public Hosted Server: https://openfec.caseyjhand.com/mcp

</div>

Tools

Nine tools for querying federal election campaign finance data:

Tool Name	Description
`openfec_search_candidates`	Find federal candidates by name, state, office, party, or cycle.
`openfec_search_committees`	Find political committees by name, type, candidate affiliation, or state.
`openfec_search_contributions`	Search itemized individual contributions or aggregate breakdowns by size, state, employer, or occupation.
`openfec_search_disbursements`	Search itemized committee spending or aggregate breakdowns by purpose or recipient.
`openfec_search_expenditures`	Search independent expenditures supporting or opposing federal candidates.
`openfec_search_filings`	Search FEC filings and reports by committee, candidate, form type, or date range.
`openfec_lookup_elections`	Look up election races and candidate financial summaries.
`openfec_search_legal`	Search FEC legal documents: advisory opinions, enforcement cases, and administrative fines.
`openfec_lookup_calendar`	Look up FEC calendar events, filing deadlines, and election dates.

`openfec_search_candidates`

Find federal candidates with optional financial totals.

Full-text name search plus filters for state, district, office, party, cycle, incumbent status
Fetch a specific candidate by FEC ID (H/S/P prefix) with full detail
Optional financial totals: receipts, disbursements, cash on hand
Pagination up to 100 results per page

`openfec_search_committees`

Find political committees (campaign, PAC, Super PAC, party).

Full-text name search plus filters for type, designation, party, state, candidate affiliation
Fetch a specific committee by FEC ID (C prefix)
Committee types: House, Senate, Presidential, Super PAC, PAC, Party
Treasurer name search

`openfec_search_contributions`

Search Schedule A contribution data with five query modes.

itemized: Individual contribution records with keyset cursor pagination
by_size: Aggregate breakdowns by contribution size range
by_state: Geographic breakdown of contributions
by_employer: Top employer aggregates
by_occupation: Top occupation aggregates
Filters: donor name, employer, occupation, city, state, ZIP, date range, amount range

`openfec_search_disbursements`

Search Schedule B spending data with four query modes.

itemized: Individual disbursement records with keyset cursor pagination
by_purpose: Aggregate by spending purpose category
by_recipient: Aggregate by payee name
by_recipient_id: Aggregate by recipient committee ID
Filters: recipient name, description, date range, amount range

`openfec_search_expenditures`

Search Schedule E independent expenditure data.

itemized: Individual expenditure records with support/oppose indicator
by_candidate: Aggregated totals per targeted candidate
Filters: committee, candidate, office, party, 24/48-hour notices, date and amount range

`openfec_search_filings`

Search FEC filings and reports.

Form types: F3 (House/Senate quarterly), F3P (Presidential), F3X (PAC/party), F24 (24-hour IE notice), F1/F2 (organizational/candidacy), F5 (IE by persons)
Report type codes: Q1/Q2/Q3, YE, monthly, pre/post election
Amendment filtering with most-recent-only option
Date range filtering by FEC receipt date

`openfec_search_legal`

Search across FEC legal document types.

Advisory opinions, MURs (enforcement cases), ADRs, administrative fines, statutes
Look up specific cases by AO number or case number
Filter by respondent, regulatory/statutory citation, penalty amount range
Offset-based pagination (up to 200 results per page)

`openfec_lookup_elections`

Look up federal election races.

search: Candidates in a race with financial totals
summary: Aggregate race financial summary
Office types: H (House), S (Senate), P (President)
ZIP code lookup to find races covering a location
Full election period expansion (4yr president, 6yr senate, 2yr house)

`openfec_lookup_calendar`

Look up FEC dates and deadlines.

events: FEC calendar events
filing_deadlines: Report due dates by type and year
election_dates: Upcoming and past election dates by state and office
Date range filtering

Resources

URI Pattern	Description
`openfec://candidate/{candidate_id}`	Federal candidate profile with current financial totals.
`openfec://committee/{committee_id}`	Political committee profile with type, designation, and financial summary.
`openfec://election/{cycle}/{office}`	Presidential or at-large election race with candidate financial totals.
`openfec://election/{cycle}/{office}/{state}`	Senate or state-level election race with candidate financial totals.
`openfec://election/{cycle}/{office}/{state}/{district}`	House district election race with candidate financial totals.

Prompts

Prompt	Description
`openfec_campaign_analysis`	Structured analysis of a candidate's financial position — fundraising trajectory, burn rate, cash reserves, donor composition, and opponent comparison.
`openfec_money_trail`	Framework for tracing the flow of money around a candidate or race — direct fundraising, PAC support, independent expenditures, and party spending.

Features

Built on @cyanheads/mcp-ts-core:

Declarative tool definitions — single file per tool, framework handles registration and validation
Unified error handling across all tools
Pluggable auth (none, jwt, oauth)
Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
Structured logging with optional OpenTelemetry tracing
Runs locally (stdio/HTTP) or via Docker from the same codebase

OpenFEC-specific:

Type-safe client wrapping the OpenFEC REST API
Multi-mode tools supporting both itemized records and aggregate breakdowns
Keyset cursor pagination for high-volume Schedule A/B/E data
Automatic retry with configurable timeout and max retries
Error sanitization strips API keys from error messages; HTTP status errors enriched with actionable hints
Two guided investigation prompts for campaign finance analysis workflows

Getting Started

Public Hosted Instance

A public instance is available at https://openfec.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

json

{
  "mcpServers": {
    "openfec-mcp-server": {
      "type": "streamable-http",
      "url": "https://openfec.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file.

json

{
  "mcpServers": {
    "openfec-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/openfec-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "FEC_API_KEY": "your-api-key"
      }
    }
  }
}

Or with Docker:

json

{
  "mcpServers": {
    "openfec-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "-e", "FEC_API_KEY=your-api-key", "ghcr.io/cyanheads/openfec-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 FEC_API_KEY=your-key bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

Bun v1.3.0 or higher (or Node ≥24)
(Optional) A free OpenFEC API key for higher rate limits (1,000 req/hr vs 30 req/hr with the default DEMO_KEY)

Installation

Clone the repository:

git clone https://github.com/cyanheads/openfec-mcp-server.git

Navigate into the directory:

cd openfec-mcp-server

Install dependencies:

bun install

Configuration

Variable	Description	Default
`FEC_API_KEY`	OpenFEC API key. Optional — defaults to `DEMO_KEY` (30 req/hr). Provide your own key (free at api.data.gov/signup) for 1,000 req/hr.	`DEMO_KEY`
`FEC_BASE_URL`	OpenFEC API base URL.	`https://api.open.fec.gov/v1`
`FEC_MAX_RETRIES`	Max retry attempts for failed API requests.	`3`
`FEC_REQUEST_TIMEOUT`	Request timeout in milliseconds.	`30000`
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`.	`stdio`
`MCP_HTTP_PORT`	Port for HTTP server.	`3010`
`MCP_HTTP_HOST`	Hostname for HTTP server.	`localhost`
`MCP_AUTH_MODE`	Auth mode: `none`, `jwt`, or `oauth`.	`none`
`MCP_LOG_LEVEL`	Log level (RFC 5424).	`info`
`LOGS_DIR`	Directory for log files (Node.js only).	`<project-root>/logs`
`STORAGE_PROVIDER_TYPE`	Storage backend.	`in-memory`
`OTEL_ENABLED`	Enable OpenTelemetry instrumentation (spans, metrics, completion logs).	`false`

Running the Server

Local Development

Build and run:

bun run rebuild
bun run start:stdio   # or start:http

Run checks and tests:

bun run devcheck      # Lint, format, typecheck, security audit
bun run test          # Runs test suite

Project Structure

Directory	Purpose
`src/mcp-server/tools/definitions/`	Tool definitions (`*.tool.ts`).
`src/mcp-server/resources/definitions/`	Resource definitions (`*.resource.ts`).
`src/mcp-server/prompts/definitions/`	Prompt definitions (`*.prompt.ts`).
`src/services/openfec/`	OpenFEC API client and domain types.
`src/config/`	Environment variable parsing and validation with Zod.
`tests/`	Unit and integration tests.
`scripts/`	Build, clean, devcheck, tree, and lint scripts.
`docs/`	Design docs and OpenAPI spec.

Development Guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

Handlers throw, framework catches — no try/catch in tool logic
Use ctx.log for domain-specific logging, ctx.state for storage
Register new tools and resources in the index.ts barrel files

Contributing

Issues and pull requests are welcome. Run checks before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

Install

Configuration

Environment variables

FEC_API_KEY

OpenFEC API key — optional (DEMO_KEY: 30 req/hr). Own key: 1000 req/hr. Free at api.data.gov.

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

claude_desktop_config.json

{
  "mcpServers": {
    "openfec-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/openfec-mcp-server@0.4.13",
        "run",
        "start:stdio"
      ],
      "env": {
        "FEC_API_KEY": "<YOUR_FEC_API_KEY>",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}