
openfec-mcp-server
io.github.cyanheads/openfec-mcp-server
Access FEC campaign finance data. Query data about candidates, money trails, and election filings.
Documentation
@cyanheads/openfec-mcp-server
Access FEC campaign finance data on candidates, money trails, and election filings via MCP. STDIO or Streamable HTTP.
Public Hosted Server: https://openfec.caseyjhand.com/mcp
Overview
US federal campaign finance data from the FEC's OpenFEC API. Search candidates, committees, and filings, trace contributions (Schedule A), disbursements (Schedule B), and independent and coordinated party expenditures (Schedules E/F), and look up election races, legal documents, and filing deadlines.
Tools
| Tool | Description |
|---|---|
openfec_search_candidates | Find federal candidates by name, state, office, party, or cycle; fetch one by FEC ID with financial totals |
openfec_search_committees | Find political committees by name, type, candidate affiliation, or state; fetch one by FEC ID |
openfec_get_committee_totals | Pre-aggregated financial totals for one committee by cycle, or ranked across committees of one entity type |
openfec_search_contributions | Itemized contributions (Schedule A) by recipient committee or by donor, or aggregates by size, state, employer, or occupation |
openfec_search_disbursements | Itemized committee spending (Schedule B), or aggregates by purpose or recipient |
openfec_search_expenditures | Independent expenditures (Schedule E) supporting or opposing candidates, itemized or totaled per candidate |
openfec_search_coordinated_expenditures | Coordinated party expenditures (Schedule F) made on behalf of a candidate |
openfec_search_filings | FEC filings and reports by committee, candidate, form type, or date range |
openfec_lookup_elections | Candidates in a federal race with their fundraising totals, or an aggregate race summary |
openfec_search_legal | Advisory opinions, enforcement cases, alternative dispute resolutions, administrative fines, and statutes |
openfec_get_legal_document | One legal document in full, including the arrays search trims away, paged by entry when too large for one response |
openfec_lookup_calendar | FEC calendar events, filing deadlines, and election dates |
Resources
| Resource | Description |
|---|---|
openfec://candidate/{candidate_id} | Candidate profile with financial totals and principal committees |
openfec://committee/{committee_id} | Committee profile with type, designation, and financial summary |
openfec://election/{cycle}/{office} | Presidential race with candidate financial totals |
openfec://election/{cycle}/{office}/{state} | Senate race, or at-large House race (district 00) with candidate financial totals |
openfec://election/{cycle}/{office}/{state}/{district} | House district race with candidate financial totals |
The same data is reachable through openfec_search_candidates, openfec_search_committees, and openfec_lookup_elections for tool-only clients.
The openfec-guide skill covers campaign-finance investigations, historical committee attribution, and coverage checks. MCP clients can read it at skill://openfec-guide/SKILL.md.
Prompts
| Prompt | Description |
|---|---|
openfec_money_trail | Trace the money around a candidate: direct fundraising, PAC support, independent expenditures, and party spending |
openfec_campaign_analysis | Structured analysis of a candidate's financial position |
Capability reference
openfec_search_candidates tool
queryname search filtered by state, district, office, party, cycle, election_year, incumbent_challenge, candidate_status, and has_raised_funds, up to 100 per page; or acandidate_idlookup (H/S/P + eight letters or digits) returning one full recordinclude_totals(default on for an ID lookup) adds per-cycletotalsrows: every totals row of the page's candidates is read, and when the 50-second call budget runs out first, the candidates read come back whole with anoticethat a candidate shown without totals may still have them on filestateandpartywider than any code OpenFEC files fail asinvalid_state_code/invalid_party_code; a leading-excludes the code after it (-GA,-DEM)- Typed errors:
candidate_not_found,inputs_not_applicable_to_id_lookup
openfec_search_committees tool
queryname search filtered by candidate_id, state, party, committee_type, designation, cycle, and treasurer_name, up to 100 per page; or acommittee_idlookup (C+ eight digits). An unknowncommittee_typeordesignationfails with OpenFEC's own list of valid values- Typed errors:
committee_not_found,inputs_not_applicable_to_id_lookup
openfec_get_committee_totals tool
mode: "single"(default) takes acommittee_idand returns one row per two-year cycle — withcycleomitted, every cycle it filed, across changes of committee type;mode: "by_entity_type"ranks every committee of oneentity_type(presidential,pac,party,pac-party,house-senate,ie-only), filterable by state, type, designation, organization type, and receipts/disbursements bounds; up to 100 per page.committee_typeandcommittee_designationtake any case; a code outside OpenFEC's sets fails asinvalid_committee_type/invalid_committee_designation- Rows carry receipts, disbursements, cash on hand, debts, and the itemized/unitemized split; the output
modesays whether rows are cycles or committees - Typed errors:
committee_id_required_for_single_mode,entity_type_required_for_group_mode,committee_totals_not_found
openfec_search_contributions tool
itemized(default) needs a scope: the recipientcommittee_idor a donor (contributor_id,contributor_name, orcontributor_employer), combinable. It also filters by occupation, city, state, ZIP, date and amount ranges, andis_individual, up to 100 rows per page.by_size/by_statetake acommittee_idorcandidate_id,by_employer/by_occupationacommittee_id- A donor-scoped page spans recipients: each recipient's record is in
committees, keyed bycommittee_id, and a donor that is itself a committee is incontributor_committees. A broadcontributor_nameorcontributor_employerwithoutcommittee_idcan time out upstream - The output
modebecomesby_size_candidateorby_state_candidatewhen scoped by candidate, a different row shape whose totals cover the full election period ending incycle(election_fullis echoed).by_sizerows carrysize_range(bucket 0,$200 and under (includes unitemized), has a nullcount);by_sizeandby_statewith neither ID return one bucket per committee and cycle, and thenoticesays so. Itemized responses carrynext_cursor,count, andcount_is_approximate - Memo entries (
memo_codeX) are labelled in the row header and counted in the pagenotice; leave them out of any sum - Typed errors:
itemized_requires_scope,aggregate_requires_committee_id
openfec_search_disbursements tool
committee_idrequired in every mode:itemized(default; recipient name, state, city, and committee ID, description, purpose category, date and amount ranges, up to 100 rows per page),by_purpose,by_recipient,by_recipient_id- Itemized responses carry
next_cursor,count, andcount_is_approximate; aggregate modes page by number. A payee that is itself a committee is inrecipient_committees, keyed byrecipient_committee_id, once per page and in full. Memo entries (memo_codeX) are labelled and counted in the pagenotice;by_purposememo_countandmemo_totalare already excluded fromcountandtotal
openfec_search_expenditures tool
itemized(default) filters by committee, candidate,support_oppose, payee, targeted office/state/district, party,is_notice, dates, and amounts;most_recentdefaults to true; up to 100 rows per page.is_noticeomitted returns 24/48-hour notices and report rows together, which overlap;falsereturns report rows,truenotices only. Spenders are incommittees, keyed bycommittee_id, unlesscommittee_idscopes the page- Notice rows and memo entries (
memo_codeX) are labelled in the row header, and a page that mixes either with other rows says how many in itsnotice; never add notices to report rows or memo entries to anything by_candidatetotals, largest first, need acandidate_idor a full race scope (candidate_office=Palone,Spluscandidate_office_state,Hplus state andcandidate_office_district), or fail asby_candidate_requires_scope. They come from periodic reports only, so in the current cycle thenoticesays spending reported so far only on a 24/48-hour notice is missing and names the itemizedis_notice: truecall that lists it, telling a caller who passedpageorelection_fullto drop them, since itemized mode rejects both
openfec_search_coordinated_expenditures tool
- Scope by spending party
committee_id, benefitingcandidate_id,cycle, payee, dates, and amounts; unscoped queries span all years - Page-based, up to 100 rows per page; rows carry
subordinate_committee_id, the committee the spending is attributed to. Spenders are incommittees, keyed bycommittee_id, unlesscommittee_idscopes the page. Memo entries (memo_codeX) are labelled and counted in the pagenotice
openfec_search_filings tool
- Filters: committee_id, candidate_id, filer_name, form_type (F3, F3P, F3X, F24, F1, F2, F5), report_type, report_year, cycle, is_amended, and receipt date range; up to 100 rows per page
most_recentdefaults to true, hiding superseded amendments; rows carry form and report type, financial totals, andpdf_url
openfec_lookup_elections tool
office(H,S,P) and an evencycleare required; Senate also needsstateand Housestateplusdistrict(00for an at-large seat such as WY or AK), unless azipscopes a search. OpenFEC files presidential races under stateUSand presidential and Senate races under district00: omit those inputs or pass those valuesmode: "search"(default) returns the race's candidates with totals andcandidate_pcc_id/candidate_pcc_name, that cycle's principal campaign committee; with azipit returns race locators (office, state, district, cycle), each headed with its race (GA-05 House 2026), to pass back asstateanddistrict.mode: "summary"returns one aggregate race row- Typed errors:
cycle_must_be_even,missing_state_for_office,missing_district_for_house,inputs_not_applicable_to_office,summary_does_not_support_zip,inputs_not_applicable_to_mode
openfec_search_legal tool
type(advisory_opinions,murs,adrs,admin_fines,statutes), query, ao_number, case_number, respondent, citations, penalty bounds, or dates; at least one is required (missing_filter), and a date bound needstypeplus adate_kindthat type records- Citations, penalty bounds, respondent, ao_number, and case_number each filter only some types; one sent with a
typeit doesn't filter fails asfilter_not_valid_for_type, and withtypeomitted the search returns only the types they all apply to, with a total over those types. On MURs and ADRs a citation can't be combined with case_number, respondent, a penalty bound, or an open/close date bound, which upstream would ignore; the two citation fields together match either one - Citations take the form upstream parses —
52 U.S.C. 30104or11 CFR 110.1(USC,C.F.R.,§, and suffixes like30104(g)are fine); a bare30106or110.1fails asinvalid_citationinstead of silently returning unfiltered results. One citation per field: upstream applies only the first citation in a value, so52 U.S.C. 30104, 52 U.S.C. 30118fails the same way - Offset paging via
from_hit/hits_returned, up to 200 per type within a 10,000-result window; a page carries every result upstream returns, and the next page starts atfrom_hit + hits_returned, with the same filters (a type that returned fewer is exhausted) - Results are trimmed:
documentsbecomesdocument_countanddocument_categories,dispositionsbecomesdisposition_countanddisposition_categories, highlights stop at 3 with their<em>match markup removed and render one per line, andcommission_votesshrink to a date and a 200-character action;openfec_get_legal_documentreturns the full record - Each result's
urlis the absolute link to its record page (fec.gov; govinfo.gov for statutes); an advisory opinion's page is built from its number
openfec_get_legal_document tool
doc_typeis the plural of a search result'sdocument_type(mur→murs);nois that result'snofield- Returns the untrimmed record, including
documents,commission_votes, anddispositions; fails aslegal_document_not_found. Every link — the record page, eachdocuments[].url, each citationurl— is absolute and renders as a Markdown link - A record over 100,000 bytes returns its scalar fields, the arrays that fit (smallest first), and
withheld— each held-back array with its entry count and size; re-call witharrayandoffsetfor that array's entries while they fit, plusnext_offset. An array the record lacks fails asarray_not_in_record
openfec_lookup_calendar tool
events(default;category, one of 18 codes, anddescription),filing_deadlines(report_type,report_year), orelection_dates(state,office,district,election_year);min_date/max_dateapply in every mode, up to 100 per page;statetakes any case- A numbered
districtfilter never matches an at-large race, and one that is not a number fails asinvalid_district; pair it withstate
openfec://candidate/{candidate_id} resource
- Candidate record merged with its financial totals and
principal_committees(current designationP, not scoped to a cycle) candidate_idcomes fromopenfec_search_candidates; fails ascandidate_not_found
openfec://committee/{committee_id} resource
- Committee record merged with its financial totals, which are absent for a committee that files no Form 3/3X/3P
committee_idcomes fromopenfec_search_committees; fails ascommittee_not_found
openfec://election/{cycle}/{office} resource
- Presidential races (
officeP), with totals for the full election period - First page only: a longer race carries
truncation_noticepointing toopenfec_lookup_elections, and an empty oneempty_result_notice
openfec://election/{cycle}/{office}/{state} resource
- Senate races, or the at-large House race of a state or territory with one seat (
officeSorH); anHrace is read as district00, soopenfec://election/2026/H/WYreturns Wyoming's House race - Same first-page limit and notices as the presidential template
openfec://election/{cycle}/{office}/{state}/{district} resource
- House district races (
officeH) - Same first-page limit and notices as the presidential template
openfec_money_trail prompt
- Arguments:
candidate_nameorcandidate_id(one required), optionalcycle - Seven steps: identify the candidate, resolve the cycle's principal committee via
candidate_pcc_id, then direct fundraising, independent expenditures, coordinated party spending, disbursements, and a synthesis
openfec_campaign_analysis prompt
- Arguments:
candidate_nameorcandidate_id(one required), optionalcycle - Seven steps: candidate overview, principal committee and per-cycle trajectory, fundraising mix, burn rate, competitive position, outside money, and an assessment
Features
Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.
OpenFEC-specific:
- Type-safe client for the OpenFEC REST API with retry and a configurable timeout; error messages have the API key stripped and HTTP failures carry recovery hints
- Cycles are even years covering two calendar years (2024 = Jan 2023 – Dec 2024); itemized Schedule A/B/E default to the current cycle when
cycleis omitted, andelection_full(default true) widens a race total to the full election period (4yr president, 6yr senate, 2yr house) - Itemized disbursements scope to a
committee_id, not acandidate_id; itemized contributions scope to the recipientcommittee_idor a donor (contributor_id,contributor_name, orcontributor_employer), never acandidate_id. Committeedesignationandprincipal_committeesreflect current designation only, so for a cycle's principal committee readcandidate_pcc_idfromopenfec_lookup_elections - Itemized Schedule A/B/E page with an opaque
next_cursor, valid only for an otherwise-identical call; other tools page by number, and legal search by offset
Agent-friendly output:
- Effective-query echo: every tool response carries
search_criteriawith the post-default filters, and an empty result carries anoticeon how to broaden it - The page is the size you ask for: every search tool sends
per_page(orhits_returned) upstream as given and returns every row it gets. Weight is shaped per row instead: null and empty fields are dropped, and every committee record a page references appears once per page — the committee itself, or one of three maps — in full on both surfaces. A large legal document pages its arrays byoffsetonce it passes 100,000 bytes per surface - Rows that must not be summed are labelled, not dropped: memo entries and 24/48-hour notices carry a marker in their
content[]header, and a page that mixes either with other rows counts them in itsnotice - Every call is held to a 50-second budget across its retries, so it settles before an MCP client's 60-second timeout; when the budget expires the response reports the last failure OpenFEC returned (a rate limit's wait, a gateway error), else a
Timeout. OpenFEC's ownQuery timed out504 is attempted once - Typed contracts: multi-mode tools echo the resolved
modeand reject a filter the mode can't apply (itemized_only_filters_in_aggregate_mode,inputs_not_applicable_to_mode) instead of dropping it; every failure carries a typedreasonandrecoverytext (a 400, 404, or 422 ends with OpenFEC's own reason, naming the parameter it rejected), state, party, and committee codes OpenFEC never files fail before the request (invalid_state_code,invalid_party_code,invalid_committee_type,invalid_committee_designation), and estimated totals are flaggedcount_is_approximate
Getting started
Connect to the hosted instance, no install:
claude mcp add --transport http openfec-mcp-server https://openfec.caseyjhand.com/mcp
Or run it locally:
claude mcp add openfec-mcp-server -- npx -y @cyanheads/openfec-mcp-server
For other clients, add this to the MCP config file:
{
"mcpServers": {
"openfec-mcp-server": {
"command": "npx",
"args": ["-y", "@cyanheads/openfec-mcp-server"]
}
}
}
An optional OpenFEC API key in FEC_API_KEY replaces the default DEMO_KEY, a small daily allowance shared by every caller on the same IP, with OpenFEC's published 1,000 requests per hour (-e FEC_API_KEY=your-key, or an env entry). For Docker or a source build, see Running the server.
Configuration
| Variable | Description | Default |
|---|---|---|
FEC_API_KEY | OpenFEC API key from api.data.gov. DEMO_KEY is a small daily allowance shared per IP; OpenFEC publishes 1,000 requests/hour for your own key. | DEMO_KEY |
FEC_BASE_URL | OpenFEC API base URL. | https://api.open.fec.gov/v1 |
FEC_MAX_RETRIES | Retry attempts for failed API requests. | 3 |
FEC_REQUEST_TIMEOUT | Per-request timeout, in ms. Each call is also capped at 50 s across its attempts. | 30000 |
MCP_TRANSPORT_TYPE | Transport: stdio or http. | stdio |
MCP_HTTP_PORT | HTTP server port. | 3010 |
MCP_SESSION_MODE | HTTP session mode: stateless, stateful, or auto. Overrides the stateless mode the server declares. | stateless |
MCP_AUTH_MODE | Authentication: none, jwt, or oauth. | none |
MCP_LOG_LEVEL | Log level (debug, info, warning, error, etc.). | info |
LOGS_DIR | Directory for log files (Node.js only). | <project-root>/logs |
STORAGE_PROVIDER_TYPE | Storage backend: in-memory, filesystem, supabase, cloudflare-kv/r2/d1. | in-memory |
OTEL_ENABLED | Enable OpenTelemetry. | false |
See .env.example for the full list of optional overrides.
Running the server
Local development
Requires Bun v1.4.4 or higher (or Node.js v24+).
-
Clone and install:
git clone https://github.com/cyanheads/openfec-mcp-server.git cd openfec-mcp-server && bun install cp .env.example .env # set FEC_API_KEY as needed -
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 # Vitest test suite bun run lint:mcp # Validate MCP definitions against spec
Docker
docker build -t openfec-mcp-server .
docker run --rm -e FEC_API_KEY=your-key -p 3010:3010 openfec-mcp-server
The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/openfec-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.
Project structure
| Directory | Purpose |
|---|---|
src/index.ts | createApp() entry point — registers tools/resources/prompts and inits the OpenFEC service. |
src/config | Server-specific environment variable parsing and validation with Zod. |
src/mcp-server/tools | Tool definitions (*.tool.ts), with shared validators and formatters in definitions/utils/. |
src/mcp-server/resources | Resource definitions (*.resource.ts). Candidate, committee, and three election-race templates. |
src/mcp-server/prompts | Prompt definitions (*.prompt.ts). Money trail and campaign analysis. |
src/services/openfec | OpenFEC API client and domain types. |
tests/ | Unit and integration tests, mirroring the src/ structure. |
scripts/ | Build, clean, devcheck, tree, changelog, and lint scripts. |
skills/ | Agent guide to campaign-finance workflows, identifiers, and coverage limits; also served over MCP. |
docs/ | Design notes and the OpenFEC OpenAPI spec. |
Development guide
See CLAUDE.md for development guidelines and architectural rules. The short version:
- Handlers throw, framework catches — no
try/catchin tool logic - Use
ctx.logfor logging,ctx.statefor storage - Register new tools and resources in the barrels at
src/mcp-server/*/definitions/index.ts - Wrap the OpenFEC API: validate raw → normalize to domain type → return the output schema; never fabricate fields the upstream response omitted
Contributing
Issues are welcome. Run checks and tests before submitting:
bun run devcheck
bun run test
License
Apache-2.0 — see LICENSE for details.
@cyanheads/openfec-mcp-servernpm install @cyanheads/openfec-mcp-server@cyanheads/openfec-mcp-servernpm install @cyanheads/openfec-mcp-serverRemote
Related Servers
io.github.cyanheads/anime-mcp-server
Search anime/manga, franchise relations, schedule, characters, rankings, studio filmography.
io.github.cyanheads/art-institute-chicago-mcp-server
Search the Art Institute of Chicago collection: artworks, artists, exhibitions, and audio guides.
io.github.cyanheads/arxiv-mcp-server
Search arXiv, fetch paper metadata, and read full-text content.