MCP Dados Brasil

mcp-dados-br

英語版

ブラジルの公開データをAIアシスタント向けツールとして提供する**MCP（Model Context Protocol）**サーバーです。Claude Desktop、Claude Code、Cursor、およびあらゆるMCPクライアントで利用できます。

インストール

恒久的なインストールが不要な、最も簡単な方法です。

uvx mcp-dados-br

Claude Desktopでの設定：

{
  "mcpServers": {
    "dados-brasil": {
      "command": "uvx",
      "args": ["mcp-dados-br"]
    }
  }
}

または、Claude Codeの場合：

claude mcp add dados-brasil -- uvx mcp-dados-br

ソースコードから

git clone https://github.com/lucianoon/mcp-dados-br
cd mcp-dados-br
uv sync

利用可能なツール

データソース	ツール	説明
IBGE/SIDRA	ibge_populacao, ibge_pib, ibge_municipios, ibge_sidra	人口、GDP、市町村の検索、および任意のSIDRA集計への汎用クエリ
Banco Central	bcb_serie, bcb_cambio, bcb_moedas, bcb_focus	名前付きショートカット（selic、ipca、cdiなど）を使ったSGS系列、PTAX為替レート、通貨一覧、Boletim Focusの予測
INMET	inmet_estacoes, inmet_dados	気象観測所の一覧と観測された毎時データ（観測データにはトークンが必要です）
Câmara dos Deputados	camara_deputados, camara_detalhes_deputado, camara_proposicoes, camara_votacoes_proposicao, camara_agenda, camara_tramitacao	下院議員、法案、採決、議事予定、審議状況
Senado Federal	senado_senadores, senado_materias, senado_votacoes	現職の上院議員、立法議案、採決結果付きの記名投票

すべてのデータソースは公式の公開APIです。INMETの毎時データを除き、 APIキーは必要ありません（詳細は以下を参照）。

設定

Claude Desktop / Cursor

設定ファイル（claude_desktop_config.jsonまたはmcp.json）に追加します。

{
  "mcpServers": {
    "mcp-dados-br": {
      "command": "uv",
      "args": ["run", "--directory", "/caminho/para/mcp-dados-br", "mcp-dados-br"]
    }
  }
}

Claude Code

claude mcp add mcp-dados-br -- uv run --directory /caminho/para/mcp-dados-br mcp-dados-br

INMETの任意トークン

観測所一覧（inmet_estacoes）は公開されています。一方、観測された 毎時データ（inmet_dados）にはINMETから発行されるトークンが必要です。 portal.inmet.gov.brから申請し、MCPクライアントで 環境変数を設定してください。

{
  "mcpServers": {
    "mcp-dados-br": {
      "command": "uv",
      "args": ["run", "--directory", "/caminho/para/mcp-dados-br", "mcp-dados-br"],
      "env": { "INMET_TOKEN": "seu-token" }
    }
  }
}

トークンがなくても、残りの18個のツールは通常どおり動作します。

streamable-httpトランスポート

標準のstdioに加えて、サーバーをリモートHTTPモードで実行できます。

MCP_TRANSPORTE=streamable-http MCP_PORTA=8000 mcp-dados-br

クライアントからhttp://localhost:8000/mcpに接続します。Dockerでの利用や、 ローカルネットワーク上でサーバーを共有する場合に便利です。デフォルトでは サーバーは127.0.0.1のみで待ち受けます。他のマシンからの接続を許可するには、 MCP_HOST=0.0.0.0を設定してください（Dockerイメージではすでに設定されています）。

変数	デフォルト	機能
MCP_TRANSPORTE	stdio	streamable-httpを設定するとHTTPモードが有効になります
MCP_HOST	127.0.0.1	待ち受けインターフェース（Dockerイメージでは0.0.0.0）
MCP_PORTA	8000	HTTPポート
MCP_AUTH_TOKEN	空	設定すると、すべてのリクエストでAuthorization: Bearer <token>が必要になります

認証（Bearer 認証は任意）

リスク： MCP_AUTH_TOKEN を設定しない場合、HTTP モードは認証されません。0.0.0.0（Docker イメージのように）で待ち受けると、ポートに到達できる人は誰でも19個のツールを呼び出し、公開 API の利用枠を消費し、あなたの INMET_TOKEN を使用できます。この状態で起動すると、サーバーはログに警告を記録します。トークンなしでポートをインターネットに公開しないでください。また、前段に TLS 対応のリバースプロキシを置くことを推奨します。平文の HTTP ではトークンがそのまま送信されます。

長くランダムなトークンを生成し、サーバーに渡します。

export MCP_AUTH_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
MCP_TRANSPORTE=streamable-http mcp-dados-br

ヘッダーがないリクエスト、別のスキームを使ったリクエスト、またはトークンが異なるリクエストには、WWW-Authenticate: Bearer を含む 401 が返されます。比較には secrets.compare_digest（定時間比較）を使用します。クライアントでは、たとえば Claude Code で次のようにヘッダーを送信します。

claude mcp add --transport http dados-brasil http://localhost:8000/mcp \
  --header "Authorization: Bearer $MCP_AUTH_TOKEN"

stdio ではトークンは適用されません。プロセスは、それを起動したクライアントとのみ通信します。

Docker

docker build -t mcp-dados-br .
docker run -p 8000:8000 \
  -e MCP_AUTH_TOKEN="$MCP_AUTH_TOKEN" \
  -e INMET_TOKEN=seu-token \
  mcp-dados-br

自分のマシン上だけで使用する場合は、ポートをループバックにのみ公開します。 docker run -p 127.0.0.1:8000:8000 mcp-dados-br

使用例

設定後、アシスタントに直接質問できます。

• 「過去6か月のIPCAはいくらですか？」
• 「今後の会合で、Selic はどうなると市場は予想していますか？」（Boletim Focus）
• 「ミナスジェライス州選出で、党 X に所属する連邦下院議員は誰ですか？」
• 「2022年のサンパウロの人口は何人ですか？ GDP はいくらですか？」
• 「ここ数日のドル PTAX はどうなっていますか？」
• 「メンタルヘルスに関する2025年の法案を検索してください」
• 「今週の下院の予定には何がありますか？」
• 「上院は PEC X にどのように投票しましたか？ 賛成・反対の票数は？」
• 「ミナスジェライス州選出の上院議員は誰ですか？」
• 「アマゾナス州には INMET のどの自動観測所がありますか？」

開発

uv sync --dev
uv run pytest              # suíte unitária (mocks)
uv run pytest -m integration   # consulta as APIs reais
uv run ruff check .
uv run mypy src

デバッグログ：MCP クライアントで MCP_LOG_LEVEL=DEBUG を設定してください。 貢献する場合は、CONTRIBUTING.md をお読みください。

アーキテクチャ

src/mcp_dados_br/
├── server.py        # Servidor MCP, registro das tools e escolha do transporte
├── auth.py          # Middleware ASGI de autenticação bearer (modo HTTP)
├── validacao.py     # Validação dos argumentos das tools (UF, moeda, datas, limites)
├── saida.py         # Resultado com texto + structuredContent
├── http.py          # Cliente HTTP compartilhado, retry e tratamento de erros
├── payload.py       # Leitura defensiva das respostas das APIs (fonte e campo no erro)
├── cache.py         # Cache TTL em memória para as respostas das APIs
└── tools/
    ├── ibge.py      # SIDRA v3 + localidades v1
    ├── bcb.py       # SGS + Olinda (PTAX e Boletim Focus)
    ├── inmet.py     # Estações e dados observacionais
    ├── camara.py    # Dados Abertos da Câmara v2
    └── senado.py    # Dados Abertos do Senado (LegisSaber)

• 2種類のトランスポート：stdio（デスクトップクライアントのデフォルト）と streamable-http（Docker／ネットワーク）。後者では MCP_AUTH_TOKEN による Bearer 認証を任意で設定できます
• URL を組み立てる前に入力を検証します：UF は27の略号のいずれか、通貨は3文字の ISO 4217、日付は ISO 形式、IBGE／SIDRA コードは数値、ID は正の値、dias／ultimas には上限を適用します。上限はツールの inputSchema にも反映され、何が入力され、何が受け付けられるかを示すエラーが MCP クライアントに返されます
• 同一のリクエストごとに10分間有効な TTL キャッシュを使用します。キーは一意で、URL とパラメーターを JSON 形式で並べ替えたものです
• ネットワーク障害および 429／502／503／504 の場合、自動で再試行します
• upstream API の形式が変わった場合（フィールド名の変更、型の変更など）、ソースとフィールドを示すツールエラー（isError: true）になります。例： BCB/PTAX からの予期しない応答：フィールド 'cotacaoCompra' がありません
• モデルが読みやすいテキスト形式で出力します。bcb_serie、bcb_cambio、camara_deputados は outputSchema を含む structuredContent も返します（日付は ISO 形式、値は数値）。テキストはフォールバックとして維持されます
• インストール済みパッケージのバージョンを含む User-Agent

ロードマップ

• v0.2 — INMET（観測所＋トークンを使った観測データ）および Boletim Focus
• v0.3 — 下院の予定、streamable-http トランスポート、CI で定期実行する統合テスト
• v0.4 — 法案の審議状況、SGS の名前付きショートカット、Docker イメージ
• v0.5 — PyPI への公開（uvx mcp-dados-br）、MCP Registry、Smithery
• v0.6 — 入力検証、HTTP モードでの Bearer 認証、構造化出力
• DOU：官報の検索（安定した公開 API の提供待ち）
• TSE：選挙結果

ライセンス

MIT