@cyanheads/openfec-mcp-server

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

Tools

Nine tools for querying federal election campaign finance data:

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

Related MCP server: FEC Campaign Finance MCP Server

Resources

Prompts

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:

{
  "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.

{
  "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:

{
  "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

1. Clone the repository:

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

2. Navigate into the directory:

cd openfec-mcp-server

3. Install dependencies:

bun install

Configuration

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

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.