congressgov-mcp-server

---

概要

Congress.gov と上院の公式採決フィードから、米国議会のデータを取得します。法案、成立した法律、議員、委員会、記名投票、指名、CRS および委員会の報告書、Congressional Record に対応しています。立法活動を確認し、法案や報告書の本文を読み、上院での承認に至るまで指名を追跡できます。

ツール

ツール	説明
congressgov_bill_lookup	法案の閲覧と取得：措置、提案者、概要、本文、関連法案
congressgov_enacted_laws	議会ごとに成立した公法および私法を閲覧
congressgov_member_lookup	州、選挙区、議会ごとに議員を検索し、議員の立法活動を取得
congressgov_committee_lookup	委員会と、その委員会に関連する法案、報告書、指名を閲覧
congressgov_roll_votes	下院および上院の記名投票と各議員の投票内容を取得
congressgov_senate_nominations	大統領指名を閲覧し、上院での承認状況を追跡
congressgov_bill_summaries	最近更新された CRS 法案概要を閲覧
congressgov_crs_reports	超党派の CRS 政策報告書を閲覧・取得
congressgov_committee_reports	法案に付属する委員会報告書を閲覧・参照
congressgov_daily_record	日刊 Congressional Record を閲覧・参照
congressgov_search_bills	ローカルの全文ミラーを通じて、法案のタイトルと CRS 概要をキーワード検索（オプトイン）

リソース

リソース	説明
congress://current	現在の議会番号、会期日程、議院情報
congress://bill-types	有効な法案種別コードの参照表
congress://member/{bioguideId}	bioguide ID による議員プロフィール
congress://bill/{congress}/{billType}/{billNumber}	議会、種別、番号による法案の詳細
congress://committee/{committeeCode}	委員会コードによる委員会の詳細

多くの MCP クライアントはツールのみをサポートし、リソースを表示しないため、法案、議員、委員会のデータには congressgov_bill_lookup、congressgov_member_lookup、congressgov_committee_lookup（操作 get）からもアクセスできます。

プロンプト

プロンプト	説明
congressgov_bill_analysis	法案を分析するための構造化されたフレームワーク
congressgov_legislative_research	議会全体にわたる政策分野の調査フレームワーク

機能リファレンス

congressgov_bill_lookup _tool

• list は 1 つの congress を閲覧し、billType と、レコードの更新日による fromDateTime／toDateTime の範囲で絞り込みます。デフォルトでは新しい順で、order: 'oldest' を指定すると古い順になります。get、actions、amendments、cosponsors、committees、subjects、summaries、text、titles、related、content には congress + billType + billNumber が必要です
• 法案の行に含まれる type と number は、それぞれ billType と billNumber として受け付けられます。法案種別コードでは大文字と小文字が区別されません。正規キーとエイリアスキーを同時に指定すると拒否されるため、各フィールドには名前を 1 つだけ送信してください
• content は textVersionIndex（0 が最新）のテキストバージョンを読み取り、content.text に 1 つの文字範囲を返します。totalCharacters、truncated、nextOffset も返されます
• summaries は任意の versionCode（00 は提出時、49 は公法）を受け付け、congressgov_bill_summaries と同様に characterOffset／characterLimit を使ってページ分割します

---

congressgov_enacted_laws _tool

• list は 1 つの congress を閲覧し、任意で lawType（pub または priv）による絞り込みができます。これは congressgov_bill_lookup にはない制定法の絞り込みです。get には lawType + lawNumber が必要で、一覧行の laws[].number（118-90）または数字のみ（90）を指定します
• get は、laws[] 配列に法律の引用情報が含まれる、制定の元となった法案レコードを返します

---

congressgov_member_lookup _tool

• 名前検索には対応していません。list は stateCode（および選挙区。全州区の場合は 0 で、stateCode が必要）、congress、currentMember で絞り込みます
• get は bioguideId（例：P000197）のプロフィールを返します。sponsored と cosponsored は、その議員の提出法案と共同提出法案を返します

---

congressgov_committee_lookup _tool

• committeeCode は議院の接頭辞（h／s／j）、文字、2 桁の接尾辞（例：hsju00）で構成されます。get、bills、reports、および上院専用の nominations は、接頭辞から chamber を判定します
• committeeCode に委員会名を指定すると、一致する委員会が 1 つだけの場合に解決され、それ以外の場合は通知とともに候補行が返されます。filter による list では、対象範囲内のすべての委員会を名前で照合し、あいまい一致には approximate: true が付与されます
• bills はデフォルトで新しい順（order）に返されます。各行にタイトルは含まれないため、行ごとに congressgov_bill_lookup の get を続けて呼び出してください

---

congressgov_roll_votes _tool

• chamber は house（デフォルト、Congress.gov API）または senate（上院の LIS フィード）です。すべての呼び出しで congress + session（1 または 2）が必要です。get／members にはさらに voteNumber が必要で、これは各会期でリセットされ、議院ごとに固有です
• list はデフォルトで新しい順になり、order: 'oldest' を指定すると古い順になります。get は質問、結果、票数、政党別内訳を返し、members は各議員の投票態度を返します
• 上院の投票記録は第 101 議会（1989 年）から始まります。上院の行には、フィードに含まれる年のない voteDate と、そこから導出された voteDateIso が組み合わされています

congressgov_senate_nominations _ツール

• list は 1 つの congress を参照します。get、actions、committees、hearings、nominees には nominationNumber（PN1000 の場合は 1000）が必要です。また、nominees には get が返す nominees 配列の ordinal も必要です
• 複数パートに分かれた指名（例：PN851）の活動は、分割された子項目（851-1、851-2、…）に保持されます。分割前の番号を指定して空のサブリソースを呼び出すと、該当する子項目を示す通知が返されます

---

congressgov_bill_summaries _ツール

• congress と billType は省略可能です（billType を指定する場合は congress が必要です）。fromDateTime／toDateTime で絞り込む対象は法案のアクション日ではなく要約の更新日時です。両方を省略すると直近 7 日間が対象になります
• シリアライズ後の文字数が 50,000 文字に達すると、ページへの行の追加が停止します（少なくとも 1 行は常に返され、pagination.nextOffset から再開できます）。25,000 文字を超える要約は、textTotalCharacters、textTruncated、textNextOffset を含むウィンドウ形式で返されます
• 1 つの法案の要約を取得する場合や、ウィンドウ形式の要約を最後まで読む場合は、congressgov_bill_lookup の summaries を使用してください

---

congressgov_crs_reports _ツール

• list はカタログを参照します。get には R40097、RL33612、IF12345 などの reportNumber が必要です
• id、reportId、report_id は reportNumber として受け付けられます。識別子キーは 1 つだけ指定してください
• get は著者、トピック、要約、ダウンロード形式を返します

---

congressgov_committee_reports _ツール

• list は 1 つの congress を参照し、任意で reportType（hrpt は下院、srpt は上院、erpt は行政府）を指定できます。get、text、content には reportType と reportNumber が必要です
• get は引用情報、タイトル、委員会、関連法案を返します。text は {type, url} 形式のリンクを一覧表示し、content はレポートを 1 つの文字ウィンドウとして読み込みます

---

congressgov_daily_record _ツール

• 次の順に参照します：list（巻）→ issues（volumeNumber で指定）→ articles（volumeNumber と issueNumber で指定）
• content は、号全体を通じた 0 始まりの articleIndex で指定した記事を、1 つの文字ウィンドウとして読み込みます。Record の記事は整形済みテキストと PDF のみを公開しているため、format: 'xml' は format_unavailable エラーになります

---

congressgov_search_bills _ツール

• 法案タイトルと CRS の要約を、AND 条件で結合した query キーワードで検索し、congress、billType、originChamber で絞り込みます。limit は 1～100、offset はページネーションに使用します
• BM25 で順位付けされた行には、congressgov_bill_lookup 用の billId と congress／billType／billNumber、および summaryPreview が含まれます。政策分野と法案全文はインデックス化されていません
• CONGRESS_MIRROR_ENABLED=true の場合のみ一覧に表示されます。bun run mirror:init でインデックスが作成されるまでは、通知とともに空の結果が返されます

---

congress://current _リソース

• 現在の議会番号、会期日程、両院の情報を返します。他のクエリの基準となります
• 公開キャッシュの有効期間は 1 時間です

---

congress://bill-types _リソース

• 8 種類の法案タイプコード（hr、s、hjres、sjres、hconres、sconres、hres、`sres）について、説明、議院、引用例を返します
• 静的なリソースで、上流への呼び出しはありません。公開キャッシュの有効期間は 24 時間です

---

congress://member/{bioguideId} _リソース

• bioguideId は大文字 1 文字と 6 桁の数字で構成されます（例：P000197）
• 議員プロフィール（氏名、州、所属政党、在任期間、役職、事務所、立法関連の件数）を返します

---

congress://bill/{congress}/{billType}/{billNumber} _リソース

• congress と billNumber は正の整数です。billType には 8 種類の法案タイプコードのいずれかを指定します
• 法案の詳細（提出者、状況、政策分野、委員会、最新のアクション）を返します

---

congress://committee/{committeeCode} _リソース

• committeeCode は、h／s／j のいずれかに続く 3～8 文字の小文字英数字です（例：hsju00）。議院は先頭の文字で決まります
• 委員会の詳細（名称、議院、小委員会、沿革、立法関連の件数）を返します

---

congressgov_bill_analysis _{プロンプト}

• 引数：congress、billType、billNumber。すべて必須です
• 要約から見通しまで、7 部構成の分析を提示するユーザーメッセージを 1 つ返します。各パートで呼び出すツールも示します

---

congressgov_legislative_research _{プロンプト}

• topic は必須、congress は省略可能で、デフォルトは現在の議会です
• CONGRESS_MIRROR_ENABLED が有効な場合、計画は congressgov_search_bills から始まります。無効な場合は、シードとなる法案、議員、委員会、または CRS レポート ID を求めます。トピックを受け付けるツールがほかにないためです

機能

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

Congress.gov 固有の機能：

• Congress.gov REST API v3 用の型安全なクライアントに加え、上院のロールコール投票を提供する上院 LIS XML フィード用クライアント
• Congress.gov API にはキーワード検索機能がないため、ツールは議会、種別、日付範囲、議院、州、選挙区で閲覧します。リスト操作では limit を 1～250（デフォルトは 20）、offset を指定してページングします
• 法案本文、委員会報告書、議会議事録の記事の content は、format に text（デフォルト）または xml を指定し、characterOffset／characterLimit の範囲（1～100,000 文字、デフォルトは 25,000 文字）を読み込みます。取得元は www.congress.gov のみに制限され、上限は 25 MB、期限は 30s です
• api.data.gov の任意の API キーを使用できます。DEMO_KEY は IP ごとに 1 時間あたり 30 リクエスト、1 日あたり 50 リクエストまで、登録済みのキーは 1 時間あたり 5,000 リクエストまで利用できます
• オプトイン式のローカル SQLite FTS5 ミラー（CONGRESS_MIRROR_ENABLED）により、法案タイトルと CRS 要約を対象としたキーワード検索を追加できます

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

• すべてのリスト応答に effectiveQuery と totalCount が含まれ、一致するものがない場合は notice が付与されます
• list に詳細専用の識別子（billNumber、voteNumber、nominationNumber、reportNumber、volumeNumber）を指定すると、代わりに使用すべき操作を示す incompatible_identity エラーが返されます
• content は offset、truncated、nextOffset を返すため、数 MB の法案を読み進めても文字を飛ばしたり重複したりしません
• 型付きエラー（document_unavailable、format_unavailable、document_fetch_failed、document_too_large、offset_past_end、not_found、rate_limited、invalid_request、upstream_error、upstream_timeout）には、それぞれ復旧のヒントが付属します

はじめに

公開ホストインスタンス

公開インスタンスは https://congressgov.caseyjhand.com/mcp で利用できます。インストールは不要です。Streamable HTTP を提供しており、各クライアントで設定形式が異なります。

Claude Code の場合：

claude mcp add --transport http congressgov-mcp-server https://congressgov.caseyjhand.com/mcp

Cline の場合（cline_mcp_settings.json）：

{
  "mcpServers": {
    "congressgov-mcp-server": {
      "type": "streamableHttp",
      "url": "https://congressgov.caseyjhand.com/mcp"
    }
  }
}

Cursor の場合（mcp.json）：

{
  "mcpServers": {
    "congressgov-mcp-server": {
      "url": "https://congressgov.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop では、Settings → Connectors からリモートサーバーを追加します。

セルフホスト／ローカル

以下を MCP クライアントの設定ファイルに追加します。

{
  "mcpServers": {
    "congressgov-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/congressgov-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "CONGRESS_API_KEY": "your-api-key"
      }
    }
  }
}

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

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

または Docker を使用します。

{
  "mcpServers": {
    "congressgov-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "CONGRESS_API_KEY=your-api-key",
        "ghcr.io/cyanheads/congressgov-mcp-server:latest"
      ]
    }
  }
}

Streamable HTTP を使用する場合は、トランスポートを設定してサーバーを起動します。

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

前提条件

• Bun v1.4.0 以降（または Node.js v24 以降）。
• 任意：api.data.gov の無料キーを使用すると、デモキーの IP ごとに 1 時間あたり 30 リクエスト、1 日あたり 50 リクエストという上限が、1 時間あたり 5,000 リクエストに引き上げられます。

インストール

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

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

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

cd congressgov-mcp-server

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

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env and set CONGRESS_API_KEY (and the mirror vars, if you want keyword search)

設定

変数	説明	デフォルト
CONGRESS_API_KEY	api.data.gov の API キーです。	DEMO_KEY
CONGRESS_API_BASE_URL	Congress.gov API のベース URL です。	https://api.congress.gov/v3
CONGRESS_MIRROR_ENABLED	ローカルの法案検索ミラーと congressgov_search_bills ツールを有効にします。	false
CONGRESS_MIRROR_PATH	SQLite ミラーインデックスのファイルシステムパスです。	.mirror/bills.sqlite3
CONGRESS_MIRROR_REFRESH_CRON	プロセス内のミラー更新に使う Cron スケジュールです（HTTP トランスポートのみ）。未設定の場合は、mirror:refresh を手動で実行します。	—
CONGRESS_MIRROR_CONGRESSES	ミラー対象とする議会番号をカンマ区切りで指定します（例：118,119）。	現在の議会＋1つ前の議会
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_SESSION_MODE	HTTP セッションモード：stateless、stateful、または auto。auto は stateful に解決されます。	stateless
MCP_AUTH_MODE	認証方式：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（debug、info、notice、warning、error など）。	info
LOGS_DIR	ログファイルのディレクトリ（Node.js のみ）。	<project-root>/logs
OTEL_ENABLED	OpenTelemetry を有効にします。	false
OTEL_EXPORTER_OTLP_ENDPOINT	トレースとメトリクス用の OTLP ベースエンドポイントです。	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	明示的に指定する OTLP ログエンドポイントです。ベースエンドポイントを設定しても、ログのエクスポートは有効になりません。	—
LOG_TOOL_FAILURE_PAYLOADS	キーに基づく秘匿化を行い、失敗した呼び出しの入力と出力を記録します。自由形式の値に含まれるシークレットは秘匿化されません。	false
LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES	失敗した呼び出しの入力または出力レコードごとの最大バイト数です。	16384

オプションのオーバーライドの全一覧は、.env.example を参照してください。

サーバーの実行

ローカル開発

• 本番バージョンをビルドして実行する：

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

• このチェックアウトから法案検索ミラーをビルドする（CONGRESS_MIRROR_ENABLED=true を指定）：

  bun run mirror:init      # full build
  bun run mirror:refresh   # incremental refresh
  bun run mirror:verify    # readiness and integrity check
  

  ミラー CLI を実行するには、このチェックアウトまたは Docker イメージのパスマッピングが必要です。npm インストールからこれらのスクリプトを実行することはできません。

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

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t congressgov-mcp-server .
docker run --rm -e CONGRESS_API_KEY=your-api-key -p 3010:3010 congressgov-mcp-server

Dockerfile のデフォルトは、HTTP トランスポート、ステートレスセッションモード、および /var/log/congressgov-mcp-server へのログ出力です。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。イメージにはミラースクリプトが含まれているため、docker exec <container> bun run mirror:init を実行すると、その場でインデックスを構築できます。

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() エントリーポイント：ツール、リソース、プロンプトを登録し、サービスを初期化して、ミラー更新をスケジュールします。
src/config/	Zod を使用した、サーバー固有の環境変数の解析と検証です。
src/mcp-server/tools/	ツール定義（definitions/*.tool.ts）と、共有の入力、フォーマット、要約ウィンドウのヘルパーです。
src/mcp-server/resources/definitions/	リソース定義（*.resource.ts）です。
src/mcp-server/prompts/definitions/	プロンプト定義（*.prompt.ts）です。
src/services/congress-api/	Congress.gov API クライアント：認証、ページネーション、レート制限です。
src/services/congress-documents/	上限付きの文書テキスト取得：ホスト許可リスト、バイト数上限、文字数ウィンドウです。
src/services/congress-mirror/	ローカルの SQLite FTS5 法案検索ミラー：取り込み、正規化、スキーマです。
src/services/senate-lis/	上院の点呼投票用 Senate LIS XML クライアントです。
src/utils/	HTML/XML 文字参照のデコードです。
scripts/	ビルド、開発チェック、リリース用ツール、および mirror:init／mirror:refresh／mirror:verify CLI です。
tests/	src/ の構成を反映した単体テストと統合テストです。

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジック内で try/catch は使用しません
• リクエスト単位のログには ctx.log、テナント単位のストレージには ctx.state を使用します
• すべてのツールは読み取り専用で、注釈には readOnlyHint: true と idempotentHint: true を指定します
• 外部 API 呼び出しはラップします。生データを検証し、ドメイン型に正規化してから、出力スキーマを返します。不足しているフィールドを捏造してはいけません

コントリビューション

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

bun run devcheck
bun run test

ライセンス

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