openfec-mcp-server

---

概要

FEC の OpenFEC API を利用した、米国連邦選挙の選挙資金データです。候補者、委員会、提出書類を検索し、献金（Schedule A）、支出（Schedule B）、独立支出および政党との協調支出（Schedules E/F）の流れをたどれます。また、選挙区、法的文書、提出期限も調べられます。stdio プロセス、ローカルの Streamable HTTP サーバー、または上記の公開ホストエンドポイントとして実行できます。

ツール

ツール	説明
openfec_search_candidates	名前、州、役職、政党、選挙周期で連邦選挙の候補者を検索します。FEC IDで候補者を取得し、財務合計を確認することもできます
openfec_search_committees	名前、種類、候補者との関係、州で政治委員会を検索します。FEC IDで委員会を取得することもできます
openfec_get_committee_totals	1つの委員会について選挙周期別に事前集計された財務合計を取得します。または、1つの団体種別に属する委員会を順位付けして取得します
openfec_search_contributions	明細付きの寄付（Schedule A）、または金額、州、雇用主、職業別の集計を取得します
openfec_search_disbursements	明細付きの委員会支出（Schedule B）、または目的、受取人別の集計を取得します
openfec_search_expenditures	候補者を支持または反対する独立支出（Schedule E）を、明細または候補者ごとの合計で取得します
openfec_search_coordinated_expenditures	候補者のために行われた政党協調支出（Schedule F）を取得します
openfec_search_filings	委員会、候補者、様式の種類、日付範囲でFECへの提出書類や報告書を検索します
openfec_lookup_elections	連邦選挙の候補者と資金調達合計、または選挙区の集計概要を取得します
openfec_search_legal	勧告的意見、執行案件、代替的紛争解決、行政罰金、法令を検索します
openfec_get_legal_document	法的文書1件の全文を取得します。検索結果では省略される配列も含まれます。1回の応答に収まらない場合は、エントリ単位でページ分割されます
openfec_lookup_calendar	FECのカレンダー上の予定、提出期限、選挙日を取得します

リソース

リソース	説明
openfec://candidate/{candidate_id}	財務合計と主要委員会を含む候補者プロフィール
openfec://committee/{committee_id}	種類、指定、財務概要を含む委員会プロフィール
openfec://election/{cycle}/{office}	候補者の財務合計を含む大統領選挙
openfec://election/{cycle}/{office}/{state}	候補者の財務合計を含む上院選挙または選挙区全体の下院選挙
openfec://election/{cycle}/{office}/{state}/{district}	候補者の財務合計を含む下院選挙区の選挙

ツールのみを利用するクライアントは、openfec_search_candidates、openfec_search_committees、openfec_lookup_electionsから同じデータを取得できます。

プロンプト

プロンプト	説明
openfec_money_trail	候補者を取り巻く資金の流れを追跡します。直接の資金調達、PACからの支援、独立支出、政党支出を確認します
openfec_campaign_analysis	候補者の財務状況を構造化して分析します

機能リファレンス

openfec_search_candidates _tool

• queryでは、名前を検索し、州、選挙区、役職、政党、選挙周期、選挙年、現職・対立候補の別、候補者の状況、資金調達の有無で絞り込めます。1ページあたり最大100件です。または、candidate_id（H/S/P＋英字または数字8文字）で検索し、1件の完全なレコードを取得できます
• include_totals（ID検索ではデフォルトで有効）を指定すると、選挙周期ごとのtotals行が追加されます。選挙周期または選挙年で合計の対象を絞る検索では、検索ページは候補者35人までに制限されます。全選挙周期を対象とする場合は5人までです。合計の取得対象にならなかった候補者はmissing_totalsに記載されます
• 型付きエラー：candidate_not_found、inputs_not_applicable_to_id_lookup

---

openfec_search_committees _tool

• queryでは、名前を検索し、candidate_id、州、政党、committee_type、designation、選挙周期、treasurer_nameで絞り込めます。1ページあたり最大100件です。または、committee_id（C＋数字8桁）で検索できます
• 型付きエラー：committee_not_found、inputs_not_applicable_to_id_lookup

---

openfec_get_committee_totals _ツール

• mode: "single"（デフォルト）では committee_id を指定し、2 年周期ごとに 1 行を返します。mode: "by_entity_type" では、1 つの entity_type（presidential、pac、party、pac-party、house-senate、ie-only）に該当するすべての委員会を順位付けして返します。州、種類、指定、組織タイプ、収入・支出の範囲で絞り込めます。1 ページあたり最大 100 件です
• 行には収入、支出、手元現金、負債、および項目別・項目別以外の内訳が含まれます。出力の mode は、行が周期単位か委員会単位かを示します
• 型付きエラー：committee_id_required_for_single_mode、entity_type_required_for_group_mode、committee_totals_not_found

---

openfec_search_contributions _ツール

• itemized（デフォルト）では committee_id が必要です。寄付者名、雇用主、職業、市、州、郵便番号、日付と金額の範囲、および is_individual で絞り込めます。1 ページあたり 30 件です。by_size／by_state では committee_id または candidate_id、by_employer／by_occupation では committee_id が必要です
• 候補者で範囲を絞ると、出力の mode は by_size_candidate または by_state_candidate になり、行の形式も変わります。項目別の応答には next_cursor、count、count_is_approximate が含まれます
• 型付きエラー：itemized_requires_committee_id、aggregate_requires_committee_id

---

openfec_search_disbursements _ツール

• すべてのモードで committee_id が必要です。itemized（デフォルト）では、受取人名、州、市、委員会 ID、説明、目的カテゴリ、日付と金額の範囲で絞り込めます。1 ページあたり 30 件です。ほかに by_purpose、by_recipient、by_recipient_id があります
• 項目別の応答には next_cursor、count、count_is_approximate が含まれます。集計モードでは番号でページを指定します

---

openfec_search_expenditures _ツール

• itemized（デフォルト）では、委員会、候補者、support_oppose、支払先、対象となる役職・州・地区、政党、is_notice（24／48 時間通知）、日付、金額で絞り込めます。most_recent のデフォルトは true です。committee_id で範囲を絞る場合は 1 ページあたり 60 件、それ以外は 30 件です
• by_candidate の集計には、candidate_id または選挙区分全体の指定が必要です（candidate_office=P のみ、S と candidate_office_state、または H と州および candidate_office_district）。指定がない場合は by_candidate_requires_scope エラーになります

---

openfec_search_coordinated_expenditures _ツール

• 支出を行う政党の committee_id、便益を受ける候補者の candidate_id、cycle、支払先、日付、金額で範囲を絞り込めます。範囲を指定しないクエリでは全年度が対象になります
• ページ単位で結果を返します。committee_id で範囲を絞る場合は 1 ページあたり 80 件、それ以外は 25 件です。行には、支出が計上される委員会である subordinate_committee_id が含まれます

---

openfec_search_filings _ツール

• 絞り込み項目：committee_id、candidate_id、filer_name、form_type（F3、F3P、F3X、F24、F1、F2、F5）、report_type、report_year、cycle、is_amended、受領日範囲。1 ページあたり 65 件です
• most_recent のデフォルトは true で、置き換えられた修正報告書は表示されません。行には書式と報告書の種類、財務合計、pdf_url が含まれます

---

openfec_lookup_elections _ツール

• office と偶数の cycle が必須です。上院の場合は state、下院の場合は state と district も必要ですが、zip で検索範囲を指定する場合は不要です
• mode: "search"（デフォルト）では、合計額と、その周期の主要選挙運動委員会を示す candidate_pcc_id／candidate_pcc_name を含む、選挙区分の候補者を返します。mode: "summary" では、選挙区分の集計行を 1 行返します
• 型付きエラー：cycle_must_be_even、missing_state_for_office、missing_district_for_house、summary_does_not_support_zip

---

openfec_search_legal _ツール

• type（advisory_opinions、murs、adrs、admin_fines、statutes）、query、ao_number、case_number、respondent、citations、penalty bounds、または日付のうち、少なくとも1つが必須です（missing_filter）。日付の範囲を指定するには、typeと、そのタイプで記録されるdate_kindが必要です
• citations、penalty bounds、respondent、ao_number、case_numberは、それぞれ一部のタイプにのみフィルターとして適用されます。フィルターが適用されないtypeと一緒に指定するとfilter_not_valid_for_typeエラーになります。typeを省略した場合、指定されたすべてのフィルターが適用されるタイプのみが検索され、それらのタイプの合計が返されます。MURとADRでは、citationをcase_number、respondent、penalty bound、open/close date boundと組み合わせることはできません。上流ではこれらが無視されるためです。2つのcitationフィールドを併用すると、どちらか一方に一致します
• citationsは、上流が解析できる形式で指定します（52 U.S.C. 30104または11 CFR 110.1。USC、C.F.R.、§、30104(g)のような接尾辞も使用できます）。30106や110.1だけを指定すると、フィルターなしの結果が黙って返されるのではなく、invalid_citationエラーになります。各フィールドにはcitationを1つだけ指定してください。上流では値の最初のcitationのみが適用されるため、52 U.S.C. 30104, 52 U.S.C. 30118も同じエラーになります
• from_hit／hits_returnedによるオフセットページングに対応しており、10,000件の結果ウィンドウ内で、タイプごとに最大200件を返します
• 結果は簡略化されます。documentsはdocument_countとdocument_categoriesに、dispositionsはdisposition_countとdisposition_categoriesになります。ハイライトは最大3件で、<em>の一致箇所マークアップが削除され、1行につき1件表示されます。また、commission_votesは日付と200文字のアクションに縮小されます。完全なレコードはopenfec_get_legal_documentで取得できます
• 各レスポンスは100,000バイト未満です。全体の結果は、次のタイプの結果が収まらなくなるまでタイプごとに追加されます。一部の結果がページから除外された場合は、ページにtruncated、shown、nextFromHitが含まれます。nextFromHitは、各タイプの続きを取得するためのfrom_hitであり、そのタイプとともに渡します

---

openfec_get_legal_document _ツール

• doc_typeには検索結果のdocument_typeの複数形（mur → murs）を指定し、noにはその結果のnoフィールドを指定します
• documents、commission_votes、dispositionsを含む、簡略化されていないレコードを返します。見つからない場合はlegal_document_not_foundエラーになります
• レコードが100,000バイトを超える場合は、スカラー項目、収まる配列（小さい順）、およびwithheldを返します。withheldには、保留された各配列のエントリー数とサイズが含まれます。配列のエントリーを取得するには、その配列に対してarrayとoffsetを指定して再度呼び出します。収まる範囲のエントリーに加えて、next_offsetが返されます。レコードに存在しない配列を指定すると、array_not_in_recordエラーになります

---

openfec_lookup_calendar _ツール

• events（デフォルト。categoryは18個のコードのいずれか、descriptionを指定）、filing_deadlines（report_type、report_year）、またはelection_dates（state、office、district、election_year）を指定します。min_date／max_dateはすべてのモードに適用され、1ページあたり最大100件を返します
• districtフィルターは、全州対象の選挙には一致しません。stateと組み合わせてください

---

openfec://candidate/{candidate_id} _リソース

• 候補者レコードに財務合計とprincipal_committees（現在の指定がPのもの。選挙周期による絞り込みなし）を統合して返します
• candidate_idはopenfec_search_candidatesから取得します。見つからない場合はcandidate_not_foundエラーになります

---

openfec://committee/{committee_id} _リソース

• 委員会レコードに財務合計を統合して返します。Form 3/3X/3Pを提出していない委員会には財務合計はありません
• committee_idはopenfec_search_committeesから取得します。見つからない場合はcommittee_not_foundエラーになります

---

openfec://election/{cycle}/{office} _リソース

• 大統領選挙（officeはP）を返し、選挙期間全体の合計を含みます
• 最初のページのみ返します。複数ページにわたる選挙にはopenfec_lookup_electionsを示すtruncation_noticeが、結果が空の場合はempty_result_noticeが含まれます

---

openfec://election/{cycle}/{office}/{state} _リソース

• 上院選挙、または単一選挙区の州における下院の全州対象選挙を返します（officeはSまたはH）
• 大統領選挙のテンプレートと同じ最初のページの制限と通知が適用されます

---

openfec://election/{cycle}/{office}/{state}/{district} _リソース

• 下院選挙区の選挙（office H）
• 大統領選挙テンプレートと同じ初回ページの上限および通知

---

openfec_money_trail _{プロンプト}

• 引数：candidate_name または candidate_id（いずれか必須）、cycle は任意
• 7 つのステップ：候補者の特定、candidate_pcc_id を使ったサイクルの主要委員会の特定、続いて直接的な資金調達、独立支出、政党による協調支出、支出、総括

---

openfec_campaign_analysis _{プロンプト}

• 引数：candidate_name または candidate_id（いずれか必須）、cycle は任意
• 7 つのステップ：候補者の概要、主要委員会とサイクルごとの推移、資金調達の内訳、資金消費率、競争上の立ち位置、外部資金、評価

特長

@cyanheads/mcp-ts-core を基盤とし、stdio と Streamable HTTP のトランスポート、切り替え可能な認証（none / jwt / oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレース機能を備えた構造化ログを提供します。

OpenFEC 固有の機能：

• OpenFEC REST API 用の型安全なクライアント。再試行と設定可能なタイムアウトに対応し、エラーメッセージから API キーを除去します。また、HTTP エラーには復旧のヒントが含まれます。
• サイクルは 2 暦年を対象とする偶数年です（2024 年 = 2023 年 1 月～2024 年 12 月）。項目別の Schedule A/B/E は、cycle が省略された場合、現在のサイクルをデフォルトにします。また、election_full（デフォルトは true）を指定すると、選挙全期間の合計範囲に拡大します（大統領は 4 年、上院議員は 6 年、下院議員は 2 年）。
• 項目別の献金と支出は、candidate_id ではなく committee_id を対象とします。委員会の designation と principal_committees が示すのは現在の指定のみです。そのため、サイクルの主要委員会を確認するには、openfec_lookup_elections から candidate_pcc_id を読み取ってください。
• 項目別の Schedule A/B/E は、不透明な next_cursor を使ってページ分割されます。このカーソルは、それ以外が同一の呼び出しでのみ有効です。ほかのツールはページ番号で、法律検索はオフセットでページ分割されます。

エージェントに適した出力：

• 有効なクエリのエコー：各ツールのレスポンスには、デフォルト適用後のフィルターを示す search_criteria が含まれます。結果が空の場合は、検索範囲を広げる方法を示す notice が含まれます。
• 各出力先のレスポンス上限は 100,000 バイトです。大量データを扱うツールでは、1 ページあたりの行数に上限を設けています。ページが要求された per_page 件に満たない場合は、truncated、shown、cap を報告します（ページ番号ベースのツールは、適用されたサイズも pagination.per_page にエコーします）。法律検索は結果全体を保留し、nextFromHit を報告します。大きな法律文書では、配列を offset でページ分割します。単一の委員会を対象とするクエリでは、委員会情報を各行に繰り返す代わりに、トップレベルの committee フィールドにまとめます。
• 型付きコントラクト：複数モードのツールは、解決された mode をエコーし、そのモードで適用できないフィルターは破棄せずに拒否します（itemized_only_filters_in_aggregate_mode、inputs_not_applicable_to_mode）。すべての失敗には、型付きの reason と recovery テキストが含まれます。推定合計には count_is_approximate のフラグが付与されます。

はじめに

公開ホストインスタンス

公開インスタンスは https://openfec.caseyjhand.com/mcp で利用できます。インストールは不要です。Streamable HTTP 経由で、任意の MCP クライアントから接続してください。

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

セルフホスト／ローカル

MCP クライアントの設定ファイルに、以下を追加してください。

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

または npx を使用します（Bun は不要です）。

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

または 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"]
    }
  }
}

Streamable HTTP の場合は、トランスポートを設定してサーバーを起動してください。

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

前提条件

• Bun v1.4.0 以降（または Node.js v24 以降）。
• 任意：OpenFEC API キー（無料）。デフォルトの DEMO_KEY では 1 時間あたり 30 件のレート制限が、1,000 件に引き上げられます。

インストール

1. リポジトリをクローンします：

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

2. ディレクトリに移動します：

cd openfec-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env and set FEC_API_KEY (optional)

設定

変数	説明	デフォルト
FEC_API_KEY	api.data.gov で取得した OpenFEC API キーです。DEMO_KEY では 1 時間あたり 30 件、自分のキーでは 1,000 件のリクエストが可能です。	DEMO_KEY
FEC_BASE_URL	OpenFEC API のベース URL です。	https://api.open.fec.gov/v1
FEC_MAX_RETRIES	API リクエストが失敗した場合の再試行回数です。	3
FEC_REQUEST_TIMEOUT	リクエストごとのタイムアウト時間（ミリ秒）です。	30000
MCP_TRANSPORT_TYPE	トランスポート：stdio または http です。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_SESSION_MODE	HTTP セッションモード：stateless、stateful、または auto です。サーバーが宣言する stateless モードを上書きします。	stateless
MCP_AUTH_MODE	認証方式：none、jwt、または oauth です。	none
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error など）です。	info
LOGS_DIR	ログファイル用のディレクトリです（Node.js のみ）。	<project-root>/logs
STORAGE_PROVIDER_TYPE	ストレージバックエンド：in-memory、filesystem、supabase、cloudflare-kv/r2/d1 です。	in-memory
OTEL_ENABLED	OpenTelemetry を有効にします。	false

オプションの上書き設定の全一覧については、.env.example を参照してください。

サーバーの実行

ローカル開発

• ビルドして実行：

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

• チェックとテストを実行：

  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

Dockerfile では、デフォルトで HTTP トランスポート、ステートレスセッションモードを使用し、ログを /var/log/openfec-mcp-server に出力します。OpenTelemetry のピア依存関係はデフォルトでインストールされます。省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	目的
src/index.ts	createApp() のエントリーポイントです。ツール、リソース、プロンプトを登録し、OpenFEC サービスを初期化します。
src/config	Zod を使った、サーバー固有の環境変数の解析と検証です。
src/mcp-server/tools	ツール定義（*.tool.ts）です。共通のバリデーターとフォーマッターは definitions/utils/ にあります。
src/mcp-server/resources	リソース定義（*.resource.ts）です。候補者、委員会、および 3 つの選挙レースのテンプレートがあります。
src/mcp-server/prompts	プロンプト定義（*.prompt.ts）です。資金の流れと選挙運動の分析に関するものです。
src/services/openfec	OpenFEC API クライアントとドメイン型です。
tests/	src/ の構成を反映した単体テストと統合テストです。
scripts/	ビルド、クリーン、devcheck、ツリー、変更履歴、リントの各スクリプトです。
docs/	設計メモと OpenFEC OpenAPI 仕様です。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md を参照してください。要点は以下のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジック内で try/catch を使わないでください。
• ログには ctx.log、ストレージには ctx.state を使用してください。
• 新しいツールとリソースは、src/mcp-server/*/definitions/index.ts のバレルファイルに登録してください。
• OpenFEC API をラップする際は、生データを検証し、ドメイン型に正規化してから、出力スキーマを返してください。上流のレスポンスに含まれていないフィールドを決して捏造しないでください。

貢献

Issue を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。