gov.br APIs MCP

govbr-apis-mcp

ブラジル政府のAPIをClaudeから呼び出せるツールに変換するMCPサーバーです。 カタログ駆動型ゲートウェイを採用しており、エンドポイントごとに個別のツールを用意する方式（数百のツールとなり、クライアントのコンテキストを圧迫します）ではなく、ローカルのYAMLカタログに登録された116のAPIを、5つの汎用ツールで操作します。

openapi_urlを宣言している項目のみ、読み込み可能な仕様があります。現在は、Câmara dos DeputadosとPortal da Transparênciaの2つで、116項目中2項目です。これらについては、describe_apiが必要に応じてOpenAPI仕様を読み込みます。それ以外の呼び出し可能な項目（下記の「現時点で呼び出し可能？」列を参照）は、説明とdocs_urlに記載されたエンドポイントを使用して、call_apiだけで呼び出します。

カタログの階層

階層	ファイル	アクセスモデル	現時点で呼び出し可能？
public	src/govbr_apis_mcp/catalog_data/public.yaml	無料 — 認証不要、または無料のAPIキーが必要（IBGE、Banco Central、Câmara、Senado、Portal da Transparência、DataJud、Ipeadata、dados.gov.br…）	はい
serpro	src/govbr_apis_mcp/catalog_data/serpro.yaml	Serproの商用サービス（loja.serpro.gov.br） — 契約したAPIごとにOAuth2クライアントクレデンシャルが必要で、呼び出しごとに課金されます	Serproとの契約がある場合：SERPRO_*変数を設定してください
meia-entrada	src/govbr_apis_mcp/catalog_data/meia_entrada.yaml	割引チケットの対象資格を確認する情報源（学生CIE、ID Jovem、PcD、e-MEC） — docs/meia-entrada.mdとPOCを参照してください	CIEは対応済み（DNEとFESN）。それ以外は手動です
conecta	src/govbr_apis_mcp/catalog_data/conecta.yaml	Conecta gov.br — 公共部門の組織のみ利用可能。探索用のスタブとして95のAPIをインデックス化しています	まだ利用できません（利用申請中）

Conecta階層は、現在のカタログに全体像を反映し、後からbase_urlと認証情報を設定することで呼び出し可能にするために用意されています。OAuth2クライアントクレデンシャルフローはすでに実装済みで、Serproでも同じフローを使用しています。

ツール

• search_catalog(query, category?) — アクセントの違いを無視したキーワード検索を行い、一致件数の合計と一覧が切り詰められたかどうかを報告します。
• list_apis(category?, status?, limit?) — エントリーを列挙します。呼び出し可能なものが先に表示されます（認証情報が設定されているかどうかではなく、カタログのステータスに基づきます。絞り込んでください。絞り込まない場合、約95件の Conecta スタブが出力の大半を占めます）。
• describe_api(api_id, path?, method?) — カタログのメタデータと OpenAPI のオペレーション一覧を返します。path を指定すると、パラメーター／リクエスト／レスポンスのスキーマ（$refs はインライン化され、深さに制限があります）も返します。JSON または YAML 形式の OpenAPI 3 と Swagger 2.0 を読み取ります。
• call_api(api_id, path, method?, query?, body?, headers?) — エンドポイントを呼び出します。ベース URL と認証情報はカタログエントリーから解決されます。
  • method は GET、HEAD、POST、PUT、PATCH、DELETE、OPTIONS のいずれかです。それ以外を指定すると、allowed_methods を含むエラーが返ります。body は POST、PUT、PATCH でのみ受け付けられます。
  • path は base_url からの相対パスです（最大3回のパーセントデコード後に \ を / として扱い、; パラメーターを削除したうえで）. および .. セグメントを含むパスと、base_url のプレフィックスから外れるパスは拒否されます。# も拒否されます（フラグメントは送信されません。リテラルの # を指定するには %23 と記述してください）。制御文字も拒否されます。
  • path に含まれるクエリー文字列は query と結合されます。query 内のキーは path に含まれるキーを置き換え、リスト値を指定するとキーが繰り返されます。
  • 呼び出し元のヘッダーは大文字と小文字を区別せずに照合され、_ は - と同じものとして扱われます。Authorization、Proxy-Authorization、Host、Cookie、Accept-Encoding に加え、接続、プロキシ、転送、メソッド上書き関連のヘッダーは削除され、ignored_headers で報告されます（全リストは server.py にあります）。管理対象の認証情報は最後に適用され、常に優先されます。名前または値が無効なヘッダーは無視されず、呼び出しは error で失敗します。
  • メソッド、本文、ヘッダー、パスは OAuth2 トークンを要求する前に検証されます。入力が無効な場合は {"error": ...} が返ります。
  • 3xx リダイレクトは追跡されません。レスポンスには location（要求された URL を基準に解決し、秘匿情報を除去したもの）が含まれます。レスポンス本文は60,000文字で切り詰められます。
• credentials_status(api_id?) — 各 API に必要な環境変数と、その設定状況を返します。また、callable として、現在 call_api がそのエントリーを受け付けるかどうかも返します（available および unstable のエントリーは対象です。requires_contract のエントリーは、環境変数が設定された場合のみ対象です）。

POC：学生向け meia-entrada

CIE コードから適格性の判定までを含む、エンドツーエンドで動作するフローです。認証情報なしのデモモードにも対応しています：poc/README.md。

インストール

python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest

Claude Code に登録します（.mcp.json または claude mcp add）：

{
  "mcpServers": {
    "govbr-apis": {
      "command": "/path/to/govbr-apis-mcp/.venv/bin/govbr-apis-mcp",
      "env": {
        "TRANSPARENCIA_API_KEY": "...",
        "DATAJUD_API_KEY": "..."
      }
    }
  }
}

PyPI からインストールする場合：uvx govbr-apis-mcp（上記のエントリーで "command": "uvx" と "args": ["govbr-apis-mcp"] を設定してください。チェックアウトは不要です）。各リリースは PyPI と MCP Registry に自動で公開されます（publish.yml）。

または、コンテナーで実行します。サーバーは stdio を使用するため、-i を付けてください：

docker build -t govbr-apis-mcp . && docker run -i --rm -e TRANSPARENCIA_API_KEY=... govbr-apis-mcp

認証情報

すべてのシークレットは、カタログ内の各エントリーで宣言された環境変数（auth_config）から取得します。 リポジトリには何も保存されません。.env.example に変数の一覧があります。無料のキーを使うエントリーには signup_url があり、Serpro の認証情報は契約に含まれています（loja.serpro.gov.br）。 credentials_status で準備状況を確認できます。

サーバーは .env ファイルを読み込まず、MCP クライアントは最小限の環境変数でサーバーを起動するため、 シェルで export してもサーバーに渡らないことがあります。変数はクライアントの env ブロック（上記の例、または claude mcp add -e KEY=value）に設定してください。コンテナーの場合は、 .env.example を .env.local などの Git 管理対象外のファイルにコピーし、コピー先に値を入力してから、 docker run --env-file .env.local で渡してください。.env.example に実際の値を決して記入しないでください。 このファイルはバージョン管理されています。

API キー（値と接頭辞を合わせた全体）の前後の空白は取り除かれ、印字可能な ASCII 文字である必要があります。 それ以外の場合は、値を出力せずに credential in <VAR> contains invalid characters を返して呼び出しが失敗します。OAuth2 のクライアント ID とシークレットは空白が取り除かれるだけです。 これらは Base64 エンコードされて送信されるため、どのようなテキストでも使用できます。エンドポイントが返す アクセストークンも、印字可能な ASCII 文字である必要があります。トークンエンドポイントが失敗すると、 レスポンス本文やシークレットを含めずに、error と token_url を返します。

認証プロファイル：none、api_key（静的ヘッダー。値の接頭辞は任意。例： DataJud の APIKey <key>）、oauth2_client_credentials（トークンエンドポイントと ID／シークレット、 メモリー内のトークンキャッシュ。現在は Serpro で使用し、Conecta では加入後に使用）。

カタログの拡張

src/govbr_apis_mcp/catalog_data/ 内の YAML ファイルにエントリーを追加します。このディレクトリはパッケージデータなので、 wheel、uvx、Docker イメージのすべてにカタログが含まれます。最低限必要なフィールドは id、name、provider、category、status、auth です。API が仕様を公開している場合は openapi_url を追加すると、コードを一切追加せずに describe_api が機能します。 .venv/bin/python scripts/scrape_conecta.py で Conecta のティアを再生成します。ページに API がない場合、 カタログで拒否される ID が含まれる場合、または現在のエントリー数の半分に満たない場合は、ファイルを変更しません （--force で上書きできるのは最後のチェックのみです）。

エントリーは読み込み時に検証されます。ID はファイル名に使用できる形式である必要があります。URL は、 許可リストにあるホスト（*.gov.br、*.leg.br、*.jus.br と、いくつかの指定ホスト）上の https URL である必要があります。 また、ホスト名に使用できる文字は [a-z0-9.-] のみです（国際化ドメイン名は Punycode で記述してください）。これは スタイル上の決まりではなく、セキュリティ上の境界です。認証情報の送信先はカタログによって決まります。 GOVBR_EXTRA_ALLOWED_HOSTS でホストを追加できるのは、そのホストに認証情報を預けても安全だと信頼できる場合に限ります。 追加したホストにも同じホスト名のルールが適用されます。

フォークせずにエントリーを上書きする場合（例：加入後に Conecta のベース URL を設定する場合）は、 GOVBR_EXTRA_CATALOG_DIR に、同じ ID のエントリーが優先される .yaml または .yml ファイルのディレクトリを指定します。 ディレクトリが存在しない場合、またはエントリーが含まれていない場合はエラーになります。同じディレクトリ内で ID が重複している場合も エラーになります。空の値は未設定として扱われます。GOVBR_CATALOG_DIR はベースカタログ全体を置き換えるため、 信頼できる入力として扱ってください。

開発

python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/ruff check .
.venv/bin/ruff format --check .
.venv/bin/pytest

CI では Python 3.12 で ruff を実行し、3.11～3.14 でテストスイートを実行した後、wheel をビルドして、 クリーンインストールからカタログを読み込みます。

セキュリティに関する注意事項

• レスポンスがディスクに書き込まれることはありません。キャッシュされるのは OpenAPI 仕様のみで、$XDG_CACHE_HOME/govbr-apis-mcp/（または ~/.cache/govbr-apis-mcp/）に 24 時間保存されます。ファイル名は sha256(api_id + "\n" + openapi_url) から生成され、IDそのものが使われることはありません。また、openapi_url が変更された場合、古い仕様が使われることはありません。OAuth2 トークンはメモリ内にのみ保持されます。
• call_api はリダイレクトを追跡しません。認証情報を含むリクエストが 3xx によって別のホストへ誘導されることはなく、レスポンスには（秘匿化された）location が含まれます。また、常に Accept-Encoding: identity を送信するため、サーバーが圧縮する理由はありません。ただし、60,000 文字の上限はデコード後のテキストに対して適用されるため、それでも圧縮するサーバーの場合、上限で切り詰める前に小さなチャンクが膨張する可能性があります（許容済みのリスクです。ロードマップを参照してください）。
• API が設定した Cookie は保存も返送もされないため、ある API が別の API に渡される Cookie を仕込むことはできません。
• 仕様の取得時は、リダイレクトを手動でのみ追跡します。追跡するのは最大 5 回までで、最初の URL と各 Location のすべてが、リクエスト前に許可リストにあるホスト上の https URL である必要があります。本文は 5 MiB までで、JSON と YAML を受け付けます（エイリアスを含む YAML、およびエイリアスに依存するマージキーは拒否されます）。また、ドキュメントには openapi または swagger が含まれている必要があります。圧縮されたレスポンスは拒否され、ダウンロード全体には 60 秒の期限が設けられています。いずれの場合も spec_error が返されます。
• httpx と httpcore のロガーは WARNING のままなので、httpx がリクエスト URL（クエリ文字列を含む）をログに記録することはありません。
• pii: true とマークされたエントリーは、個人データ（CPF、氏名、写真）をクライアントのトランスクリプトに返します。現在該当するのは meiaentrada-cie-validador、fesn-cie-validador（認証情報がなくても呼び出し可能で、利用コードを持つ人は誰でもコード所有者のデータを取得できます）、および Serpro の 3 つのエントリーです。

ロードマップ

• 公的機関として Conecta に加入 → ゲートウェイのベース URL と認証情報を設定
• Conecta の各エントリーに API ごとの OpenAPI URL を設定（各詳細ページからリンク）
• Serpro のトライアルモード切り替え（公開済みのデモトークンで -trial ベース URL を呼び出す）
• 有料の Serpro API に対する呼び出しごとのコスト制限
• 圧縮された上流レスポンスの展開サイズ制限
• API conecta-id-jovem について SNJ へ請願（民間機関に対応）
• DNE データベースにない CIE の代替書類（DCE および州の団体）

ライセンス

MIT — LICENSE を参照してください。