brasilapi-mcp

一个自行编写的 Model Context Protocol (MCP) 服务器，它将公共 BrasilAPI 作为工具暴露给 LLM 客户端（Claude Desktop、Claude Code 或任何 MCP 主机）调用：可查询 CEP、CNPJ、银行、FIPE 车辆价格、全国节假日，以及 DDD 区号。

葡萄牙语版 README

为什么会有这个项目

使用别人开发的 MCP 服务器很容易；我想证明我可以构建一个 — 包括工具 schema、类型化 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 — 一条命令：

claude mcp add brasilapi -- brasilapi-mcp

然后用自然语言提问：“CEP 01001-000 的地址是什么？” 或 “列出 2026 年的全国节假日”，模型就会调用对应的工具。

设计 — 为何测试在离线状态下进行

网络被放在一个可注入的边界之后。BrasilAPIClient 接受一个可选的 httpx.Client/传输层，因此测试套件会传入一个带有预设 JSON 的 httpx.MockTransport，并在完全没有真实网络 I/O 的情况下运行。工具主体是对普通同步函数的薄封装，这些函数显式接收客户端，因此逻辑可以独立进行单元测试；BrasilAPIError 会变成模型可读的简洁消息，而不是 traceback。

测试

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

测试套件覆盖了客户端（每个端点、输入规范化、404/500 处理）针对模拟传输层的测试、工具逻辑函数，以及服务器的工具注册。整个过程不会访问网络。

关于数据的一点说明

BrasilAPI 是一项公共服务，不需要密钥；本服务器不存储任何机密，也不读取任何环境变量。实时响应归 BrasilAPI 及其上游数据源所有。

许可证

MIT — 参见 LICENSE。