.codex-plugin— 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:

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

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

1. Navigate into the directory:

cd openfec-mcp-server

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