brasilapi-mcp

自作の Model Context Protocol (MCP) サーバーであり、公開されている BrasilAPI を、LLMクライアント（Claude Desktop、Claude Code、または任意のMCPホスト）が呼び出せるツールとして提供します：CEP、CNPJ、銀行、FIPE車両価格、国民の祝日、DDD市外局番を検索できます。

ポルトガル語版README

なぜこれを作ったのか

他人のMCPサーバーを利用するのは簡単です。私が証明したかったのは、自分で構築できるということです — ツールスキーマ、型付きHTTPクライアント、そして全体をテスト可能に保つ境界。BrasilAPIはうってつけです：APIキーが不要で公開データを提供しているため、誰でもこれをクローンしてすぐに実行でき、すべてのツールはネットワークに触れることなくテストで検証されます。

Related MCP server: MCP Brasil API

ツール

インストール

pip install -e .

依存関係は mcp（公式Python SDK、v2）と httpx だけです。

実行

brasilapi-mcp            # runs the MCP server over stdio (what an MCP client launches)
brasilapi-mcp --help     # prints usage and exits, without opening a socket

サーバーはstdio経由でMCPを話します — 通常は手動で実行しません。MCPクライアントが起動して通信します。python -m brasilapi_mcp.server でも実行できます。

クライアントへの組み込み

Claude Desktop — claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "brasilapi": {
      "command": "brasilapi-mcp"
    }
  }
}

brasilapi-mcp がPATHにない場合は、command にvenvのスクリプト（例：Windowsでは .../.venv/Scripts/brasilapi-mcp）を指定するか、"command": "python", "args": ["-m", "brasilapi_mcp.server"] を使用してください。

Claude Code — コマンド1つ：

claude mcp add brasilapi -- brasilapi-mcp

その後、平易な言葉で 「CEP 01001-000の住所は？」 や 「2026年の国民の祝日を一覧して」 と尋ねると、モデルが対応するツールを呼び出します。

設計 — なぜオフラインでテストするのか

ネットワークは注入可能な境界の背後にあります。BrasilAPIClient はオプションの httpx.Client／トランスポートを受け取るため、テストスイートは固定JSONを備えた httpx.MockTransport を渡し、実際のネットワークI/Oなしで実行します。ツール本体は、クライアントを明示的に受け取る素の同期関数の薄いラッパーであり、ロジックは単体でユニットテスト可能です。また BrasilAPIError は、トレースバックではなく、モデルが読み取れる明確なメッセージになります。

テスト

pip install -e ".[dev]"
pytest -q

テストスイートは、モックトランスポートに対するクライアント（すべてのエンドポイント、入力の正規化、404/500の処理）、ツールのロジック関数、サーバーのツール登録をカバーしています。ネットワークには一切アクセスしません。

データに関する注意

BrasilAPIは公開サービスであり、キーは不要です。このサーバーはシークレットを保存せず、環境変数も読み取りません。実際のレスポンスはBrasilAPIおよびその上流ソースに帰属します。

ライセンス

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