GovQL

govql-mcp-server

GovQL 用の MCP（Model Context Protocol）サーバーです。Claude Desktop、Claude Code、Cursor などの AI クライアントから、特別な HTTP 接続設定をせずに、api.govql.us/graphql の米国議会 GraphQL API に直接アクセスできます。

設計上の理由（FastMCP-Python を選んだ理由、パススルーと厳選機能を組み合わせる方針、v0.4 までのロードマップ）については、 design.md をご覧ください。

このサーバーでできること

エージェントに、次のような質問ができます。

• 「直近の指名に対して、バーモント州の2人の上院議員はどのように投票しましたか？」
• 「第118議会の任期中に所属政党を変えた議員は誰ですか？」
• 「アリゾナ州第3選挙区の代表者は誰ですか？」
• 「直近の議会での、サンダース上院議員とムルコウスキー上院議員の議事妨害終結決議に関する投票記録を比較してください。」
• 「現議会で、共和党と最も頻繁に同じ投票をした民主党議員は誰ですか？」

エージェントが適切なツールを選び、稼働中のスキーマに対する GraphQL クエリを作成して、応答を解析します。API を手動で扱う必要はありません。

インストール

このサーバーは、クライアントごとのサブプロセスとして stdio 経由で実行されます。使用するクライアントを選んでください。

Claude Desktop

claude_desktop_config.json を編集します（設定 → 開発者 → 設定を編集）：

{
  "mcpServers": {
    "govql": {
      "command": "uvx",
      "args": ["govql-mcp-server"]
    }
  }
}

Claude Desktop を再起動します。ツールパネルに govql ツールが表示されます。

Claude Code

プロジェクト内の .mcp.json（またはグローバル設定の場合は ~/.mcp.json）に追加します：

{
  "mcpServers": {
    "govql": {
      "command": "uvx",
      "args": ["govql-mcp-server"]
    }
  }
}

Cursor

設定 → MCP → サーバーを追加します。上記と同じ command / args を指定します。

その他のクライアント

stdio サーバーに対応する MCP 互換クライアントであれば、どれでも使用できます。コマンドは uvx govql-mcp-server で、引数は必要ありません。

ツール

ツール	目的
execute_graphql	GovQL エンドポイントに対して任意の GraphQL クエリを実行します。結果と last_ingest タイムスタンプを返すため、エージェントはデータの鮮度を判断できます。
list_types	GovQL スキーマ内のすべての型について、名前と種類を返します。任意の kind フィルター（"OBJECT"、"INPUT_OBJECT"、"ENUM" など）でさらに絞り込めます。クエリ可能な対象がわからない場合は、まずここから始めてください。
describe_type	1つの型の詳細（フィールド、引数のシグネチャ、入力フィールド、列挙値）をすべて返します。クエリを作成する前に、list_types の後で呼び出して特定の型の構造を確認してください。
find_legislator	議員の bioguide id がわからない場合に、名前、政党、州、院、選挙区で議員を検索します。政党／州／院／選挙区は議員の各任期に一致します（選挙区は下院のみ）。current_only（デフォルト）は現職議員に絞り込みます。各議員の bioguideId と現在の政党／州／院／選挙区を含む簡潔な一覧を返します。
find_vote	カテゴリー、院、議会で議場採決を検索します（新しい順）。または、投票の question をキーワード検索できます。topic は質問文（法案の略称を含む）に一致します。主題の完全なインデックスではないため、手続き上の投票は見つからず、法案の主題もまだ登録されていません。各 voteId を含む簡潔な一覧を返します。
get_legislator	bioguide id で指定した1人の議員の詳細（氏名、略歴、各任期の完全な履歴（期間中の政党／州／院／選挙区）と current ブロック）を返します。
get_vote_with_positions	投票 ID で指定した1件の投票について、集計結果と政党別内訳を返します。任意で、個々の議員の投票内容（政党／州／投票内容によるフィルター）も取得できます。
get_voting_record	事前計算された要約から、議会ごとの議員の投票行動（参加率と党議拘束への同調率）を返します。
compare_voters	議会と院ごとに、2人の議員がどの程度同じ投票をしたかを、投票一致率とともに示します。
find_party_defectors	議会内で、自党の多数派と最も一致しなかった議員を返します。政党／院による絞り込みも指定できます。

設定

環境変数はすべて省略可能です。エンドユーザー向けには、パッケージの設定は不要です。

環境変数	デフォルト	用途
GOVQL_ENDPOINT	https://api.govql.us/graphql	クエリを実行するエンドポイントです。ローカルの開発スタックを指定する場合は、値を上書きします。
GOVQL_TIMEOUT_MS	30000	リクエストごとの HTTP タイムアウトです。
LOG_LEVEL	INFO	ログレベルです。ログは stderr のみに出力されます（stdout は MCP トランスポート用に確保されています）。

制限（上流 API によって適用）

• 最大クエリ深度：10
• 最大クエリ複雑度：約100億ポイント（first: N は子要素のコストを N 倍します。深くネストされたクエリでは、ページサイズを適切に抑えてください）
• レート制限：送信元 IP あたり100リクエスト／60秒

深度または複雑度の違反は、ツールのレスポンス内の GraphQL errors エントリーとして返されるため、エージェントはクエリを調整して再試行できます。

データの鮮度

execute_graphql の各レスポンスには、ISO 形式のタイムスタンプ last_ingest が含まれます。 投票データは毎時、議員データは毎日更新されます。

ステータス

0.4.0 時点で、サーバーは3つの基本ツール（execute_graphql、list_types、describe_type）に加え、厳選された 発見 ツール（find_legislator、find_vote）、エンティティごとの詳細 ツール（get_legislator、get_vote_with_positions）、分析 ツール（get_voting_record、compare_voters、find_party_defectors）を提供しており、厳選された発見／詳細／分析ツール群は完成しています。残る most_agreeing_pairs と法案／委員会ツールは v0.4 以降の対応です。法案／委員会ツールは GovQL のデータ登録待ちで、most_agreeing_pairs はサーバー側の超党派ランキング集計機能の実装待ちです。詳しくはdesign.mdをご覧ください。

リンク

• GovQL プロジェクトサイト
• GraphQL API
• ソースコード／課題