MCP Brasil API

通过模型上下文协议（MCP）将巴西API接入所有大型语言模型（LLMs）

概述

MCP Brasil API 是一个开源项目，它通过 模型上下文协议（MCP） 提供来自 Brasil API 的数据。该项目充当通用适配器（类似于AI集成中的USB-C接口），将巴西的数据端点转换为标准化的MCP服务，便于AI助手、大型语言模型和使用MCP标准的应用程序访问本地信息。

可用资源

• CEP查询：从CEP获取详细的地址信息
• CNPJ查询：从CNPJ恢复公司注册数据
• DDD查询：查询巴西DDD所覆盖的州和城市
• 汇率查询：查询与雷亚尔配对的国际汇率
• 银行信息查询：根据银行名称或代码查询银行信息

为什么选择MCP？

随着LLMs与真实数据之间集成需求的增长，模型上下文协议（MCP）提供了以下优势：

• 标准化集成：通过单一协议连接多个数据和服务
• 可扩展性：无需更改客户端逻辑即可添加或替换MCP服务器
• 安全性和效率：以最佳的安全性和性能实践管理集成
• 灵活性：根据需要轻松扩展到新的Brasil API端点

安装

# 通过pip安装
pip install mcp-brasil-api

# 或者克隆仓库
git clone https://github.com/lucianfialho/mcp-brasil-api
cd mcp-brasil-api
pip install -e .

配置

基于.env.example创建一个.env文件，并设置如下内容：

API_BASE_URL=https://brasilapi.com.br/api
USER_AGENT=brasil-api/1.0

使用

运行MCP服务器

# 启动服务器
brasil-api-mcp

使用Smithery配置

项目包括Smithery的配置，允许快速启动：

# smithery.yaml中的配置
api_base_url: "https://brasilapi.com.br/api"
user_agent: "brasil-api/1.0"

使用MCP客户端的示例

from mcp.client import McpClient

# 连接到MCP Brasil API服务器
client = McpClient("http://localhost:8000")

# 列出可用工具
tools = client.list_tools()
print(tools)

# 查询CEP
cep_info = client.invoke_tool("consultar_cep", "01001-000")
print(cep_info)

# 查询CNPJ
cnpj_info = client.invoke_tool("consultar_cnpj", "00.000.000/0001-91")
print(cnpj_info)

# 查询DDD
ddd_info = client.invoke_tool("consultar_ddd", "11")
print(ddd_info)

# 查询节假日
feriados_info = client.invoke_tool("consultar_feriados", "1989")
print(feriados_info)

# 查询货币兑换率对比雷亚尔
cambio_info = client.invoke_tool("consultar_cambio", {"moeda": "USD"}, {"data": "2025-05-02"})
print(cambio_info)

# 查询货币兑换率对比雷亚尔
cambio_info = client.invoke_tool("consultar_cambio_info", "USD", "2025-05-02")
print(cambio_info)

# 查询银行信息
banco_info = client.invoke_tool("consultar_banco_info", "1")
print(banco_info)

# 查询一年的节假日
feriados_info = client.invoke_tool("consultar_feriados", "2205")
print(feriados_info)

与LLMs（Claude、ChatGPT等）的集成

from anthropic import Anthropic
from mcp.client import McpClient

# 配置MCP客户端
mcp_client = McpClient("http://localhost:8000")
tools = mcp_client.list_tools()

# 配置Claude客户端并使用MCP工具
anthropic = Anthropic()
response = anthropic.messages.create(
    model="claude-3-5-sonnet-20240229",
    max_tokens=1000,
    temperature=0,
    system="您可以通过MCP访问巴西数据。",
    messages=[{
        "role": "user", 
        "content": "查找关于CEP 01001-000的信息"
    }],
    tools=tools  # 注册MCP Brasil API工具
)

项目结构

mcp-brasil-api/
├── src/
│   ├── tools/           # MCP工具实现
│   │   ├── cep.py       # CEP查询工具
│   │   └── cnpj.py      # CNPJ查询工具
│   ├── utils/           # 工具函数
│   │   ├── api.py       # Brasil API的HTTP客户端
│   │   ├── formatters.py # 数据格式化
│   │   └── validators.py # 数据验证
│   └── config.py        # 应用配置
├── server.py            # 主MCP服务器
├── Dockerfile           # 容器化
├── pyproject.toml       # Python包配置
└── smithery.yaml        # Smithery配置

发展路线图

• [x] CEP查询
• [x] CNPJ查询
• [x] DDD查询
• [x] 汇率支持
• [x] 银行和金融机构支持
• [x] 国家假日支持
• [ ] 利率和经济指数
• [ ] 货币报价

🤝 贡献

欢迎贡献！在提交拉取请求之前，请阅读我们的贡献指南。

1. 分叉项目
2. 创建您的资源分支（git checkout -b feature/novo-recurso）
3. 提交您的更改（git commit -m '添加新功能'）
4. 推送到分支（git push origin feature/novo-recurso）
5. 打开一个拉取请求

📄 许可证

本项目采用MIT许可证——详情见LICENSE文件。

🙏 致谢

• Brasil API 提供公共数据
• MCP（模型上下文协议） 标准化了模型与数据源之间的通信