openfec-mcp-server

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

  


</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:

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

1. Navigate into the directory:

cd openfec-mcp-server

1. 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.