MCP协议实战：构建巴西央行数据查询AI助手

1. 项目概述：一个为巴西开发者量身打造的代码助手

最近在GitHub上看到一个挺有意思的项目，叫SidneyBissoli/bcb-br-mcp。光看名字，可能很多朋友会有点懵，这串字母组合到底意味着什么？简单来说，这是一个专门为巴西开发者（或者说，任何需要处理巴西金融和商业数据的开发者）设计的“模型上下文协议”（Model Context Protocol， 简称 MCP）服务器。

MCP这个概念，如果你用过像Claude Desktop、Cursor这类集成了AI编程助手的工具，应该不陌生。它本质上是一个标准协议，允许外部的数据源、工具或服务，以一种安全、结构化的方式，被AI助手（比如Claude）调用和访问。你可以把它想象成给AI助手安装了一个个“专业插件”，让它不再仅仅依赖训练时学到的通用知识，而是能实时获取特定领域、特定公司的专有数据。

那么，bcb-br-mcp这个“插件”是干什么的呢？它的核心功能，是让AI助手能够直接查询巴西中央银行（Banco Central do Brasil， 简称 BCB）官方发布的各类经济和金融数据。对于在巴西工作的数据分析师、金融科技开发者、经济学家，或者任何需要基于巴西宏观经济指标（如利率、通胀率、汇率、信贷数据等）进行应用开发、报告生成或决策支持的人来说，这无疑是一个能极大提升效率的神器。

想象一下这个场景：你正在用Cursor写一段Python代码，需要分析巴西过去一年的基准利率（SELIC）变化对市场的影响。传统做法是，你需要中断编码，打开浏览器，手动去巴西央行的网站（比如www.bcb.gov.br）上寻找对应的API文档，然后写一段HTTP请求代码去获取数据，处理JSON响应，最后才能把数据喂给你的分析模型。这个过程繁琐、割裂，而且容易出错。

而有了bcb-br-mcp，你只需要在AI助手的聊天框里用自然语言问一句：“获取巴西央行过去12个月的SELIC利率历史数据”，AI助手就能通过这个MCP服务器，直接、安全地调用巴西央行的官方API，并把结构化的数据结果返回给你，甚至能根据你的要求直接生成可视化的代码片段。这相当于把专业的数据查询能力，无缝嵌入到了你的开发工作流和思考过程中。

这个项目由 Sidney Bissoli 维护，它解决的核心痛点非常明确：桥接通用AI编程助手与巴西本土化、权威金融数据源之间的鸿沟。它不是为了取代专业的金融数据终端，而是为日常开发、快速原型验证、教育学习等场景，提供了一个轻量、便捷且免费的自动化入口。接下来，我们就深入拆解这个项目的设计思路、技术实现以及如何把它用起来。

2. 核心架构与设计思路拆解

要理解bcb-br-mcp的价值，我们得先弄明白MCP协议和巴西央行数据生态这两个关键背景。

2.1 MCP协议：AI的“可插拔”能力扩展

MCP不是一个具体的软件，而是一个开放协议。它的设计目标很清晰：让AI应用（客户端）能够安全、可控地调用外部资源（服务器）。你可以把它类比为计算机的“设备驱动”模型。你的操作系统（AI应用）需要打印，但它本身不造打印机，它通过一个标准的打印驱动协议（MCP）与各种品牌的打印机（数据源/工具）通信。

在这个模型里：

• MCP客户端：比如Claude Desktop、Cursor IDE。它们内置了MCP客户端能力，知道如何按照协议发送请求和解析响应。
• MCP服务器：比如bcb-br-mcp。它扮演“设备驱动”的角色，专门负责与某个特定的外部系统（巴西央行API）对话，并将结果格式化成MCP协议规定的格式返回给客户端。
• 协议本身：定义了一套标准的“语言”，包括资源（Resources， 可查询的数据）、工具（Tools， 可执行的操作）和提示（Prompts， 可复用的对话模板）等概念。

这种设计的精妙之处在于解耦和安全。AI应用开发者不需要为每一个数据源都重写集成代码；数据源提供者（或第三方开发者）可以独立开发MCP服务器，只要遵循协议，就能被所有兼容MCP的客户端使用。同时，所有数据访问都通过本地或受信任的服务器进行，用户的数据和查询不会泄露给AI模型提供商。

bcb-br-mcp正是这样一个遵循MCP协议的“巴西央行数据驱动”。它封装了与BCB API交互的所有复杂性，向AI助手暴露出一组简单、清晰的“工具”，比如search_bcb_series（搜索数据序列）、get_bcb_series_data（获取序列数据）。

2.2 巴西央行数据API：SGS与更多

巴西中央银行通过其“时间序列管理系统”（Sistema Gerenciador de Séries Temporais， SGS）向公众提供了海量的经济金融时间序列数据。这是巴西最权威的宏观经济数据来源之一。

SGS的API（通常被称为“BCB SGS API”）是RESTful风格的，但直接使用它有几个小门槛：

1. 数据编码：每个经济指标（如SELIC利率、IPCA通胀指数）都有一个唯一的数字编码。你需要知道或去查找这个编码。
2. 参数构造：API请求需要正确构造查询参数，如数据起始结束日期、返回格式等。
3. 响应处理：返回的数据是特定的JSON或XML格式，需要解析和清洗才能用于分析。
4. 速率限制：虽然免费，但可能有访问频率限制。

bcb-br-mcp的设计思路，就是把这些门槛全部抹平。它内部维护了（或提供了查询机制）常见经济指标的编码映射表。当用户通过AI助手说“我想看IPCA数据”时，MCP服务器能自动将“IPCA”翻译成对应的SGS编码（例如，消费者价格指数IPCA的编码是433）。然后，它代表用户向BCB SGS API发起正确的HTTP请求，获取数据，并将复杂的原始响应转换成干净、整齐的表格或JSON对象，最后通过MCP协议返回给AI助手呈现给用户。

注意：除了最核心的SGS数据，巴西央行可能还有其他数据接口（如汇率、银行统计等）。一个设计良好的bcb-br-mcp服务器可能会逐步集成这些不同的端点，通过统一的MCP工具接口暴露，让用户无需关心数据到底来自央行的哪个子系统。

2.3 项目定位：轻量、专注与开源

从项目名称和仓库结构，我们可以推断出它的几个关键设计选择：

• 轻量级：它很可能是一个用Python或Node.js等脚本语言编写的、依赖较少的服务。目标是易于安装、配置和运行。
• 专注性：它只做一件事，并且做好——对接巴西央行数据。它不会尝试去集成纽约联储或欧洲央行的数据，这种专注使得它更易于维护和保持稳定。
• 开源：作为GitHub上的公开项目，它允许社区贡献代码、报告问题、扩展功能。例如，社区可以共同维护一个更全面的“指标名称-to-SGS编码”的映射字典。
• 配置驱动：很可能通过一个简单的配置文件（如config.json或环境变量）来设置，比如是否使用本地缓存、自定义API端点（如果BCB的地址有变化）等。

这种设计使得它非常适合个人开发者、小型团队或教育机构使用。你不需要购买昂贵的金融数据终端许可证，也不需要搭建复杂的数据管道，只需要运行这个服务器并配置好你的AI助手，就拥有了一个强大的巴西经济数据查询助手。

3. 核心功能与实操部署详解

了解了设计思路，我们来看看这个MCP服务器具体提供了哪些能力，以及如何一步步把它运行起来。

3.1 核心功能工具解析

一个典型的bcb-br-mcp服务器会通过MCP协议向AI助手提供以下几类“工具”：

1. 数据序列搜索 (search_series或search_bcb_series)

   • 作用：当你不确定某个经济指标的具体SGS编码时，可以使用这个工具。例如，你可以让AI助手“搜索关于失业率的数据序列”。
   • 内部流程：MCP服务器可能会在本地维护一个索引，或者更实时地，通过调用BCB API的某个搜索端点（如果存在），或使用一个预定义的、包含常见指标名称和编码的映射表，来返回匹配的序列列表，包括序列编码、描述、频率（日、月、年）等元数据。

2. 数据获取 (get_series_data或get_bcb_series_data)

   • 作用：这是最核心的工具。给定一个或多个SGS序列编码（或通过搜索工具得到的编码），以及起始和结束日期，获取具体的时间序列数据。
   • 参数示例：
     • series_codes:[432, 433](可能代表IGP-DI通胀指数和IPCA通胀指数)
     • start_date:2023-01-01
     • end_date:2023-12-31
   • 内部流程：服务器构造对BCB SGS APIhttps://api.bcb.gov.br/dados/serie/bcdata.sgs.{codigo}/dados?formato=json&dataInicial={start}&dataFinal={end}的请求（具体URL格式以实际项目为准）。并发请求多个序列，然后汇总、清洗数据（例如，处理空值、统一日期格式），最后打包成MCP响应。

3. 元数据查询 (get_series_info)

   • 作用：获取某个特定数据序列的详细说明，包括单位、季节性调整情况、来源等。这有助于正确理解和使用数据。

4. 最新值查询 (get_latest_value)

   • 作用：快速获取某个关键指标（如当前SELIC利率）的最新值，而无需获取整个历史序列。

在实际与AI助手对话时，你可能会这样使用：

你：“获取从2022年到现在的巴西美元兑雷亚尔汇率数据。” AI助手（通过MCP工具）：“好的，我将调用‘获取数据序列’工具。我识别到‘美元兑雷亚尔汇率’对应的常用编码是 `1`。正在为您查询...” （片刻后） AI助手：“已获取数据。期间内汇率从约5.2 BRL/USD波动至约4.9 BRL/USD。这是前5条和后5条数据预览：[以表格形式展示]。需要我为您绘制趋势图或进行简要分析吗？”

3.2 本地部署与配置逐步指南

假设项目是用Python编写的（这是实现MCP服务器的常见选择），以下是部署的典型步骤。请务必以项目仓库的README.md最新说明为准，以下流程是基于常见模式的推演。

步骤1：环境准备确保你的系统已安装：

• Python 3.10+：这是运行大多数现代Python项目的基础。
• Git：用于克隆代码仓库。
• 一个兼容MCP的客户端：如Claude Desktop。你需要知道如何配置Claude Desktop来添加自定义MCP服务器。

步骤2：获取项目代码打开终端（命令行），执行：

git clone https://github.com/SidneyBissoli/bcb-br-mcp.git cd bcb-br-mcp

这会将该项目的所有源代码下载到你的本地bcb-br-mcp文件夹中。

步骤3：安装依赖项目根目录下通常会有一个requirements.txt或pyproject.toml文件，列出了所有必需的Python库。使用pip安装它们：

# 推荐先创建一个虚拟环境（可选但最佳实践） python -m venv .venv # 在Windows上激活： .venv\Scripts\activate # 在macOS/Linux上激活： source .venv/bin/activate # 安装依赖 pip install -r requirements.txt

关键依赖可能包括：mcp(MCP的Python SDK)、httpx或requests(用于HTTP请求)、pydantic(用于数据验证)等。

步骤4：配置（如果需要）检查项目文件夹内是否有如.env.example、config.yaml或config.json之类的配置文件示例。你可能需要复制一份并填写自己的配置。

• 可能需要的配置项：
  • BCB_API_BASE_URL: 巴西央行API的基础地址（通常无需修改，除非官方变更）。
  • CACHE_ENABLED: 是否启用本地缓存以减少对API的重复请求（建议开启）。
  • CACHE_TTL: 缓存存活时间（例如3600秒）。
  • REQUEST_TIMEOUT: 请求超时时间。 如果项目设计为“开箱即用”，可能完全无需配置。

步骤5：运行MCP服务器根据项目说明，启动服务器。常见方式是通过一个Python脚本：

python src/server.py

或者，如果项目使用了uvicorn等ASGI服务器：

uvicorn src.server:app --host 0.0.0.0 --port 8080

服务器启动后，通常会监听在本地的某个端口（如8080），并输出日志表明它已准备好接受来自MCP客户端的连接。

实操心得：第一次运行时，务必关注启动日志。如果有任何依赖缺失或配置错误，日志会给出明确的错误信息。一个健康的启动日志会显示加载了哪些工具、监听的地址和端口。

步骤6：在Claude Desktop中配置这是最关键的一步，将你的AI助手与这个本地服务器连接起来。

1. 打开Claude Desktop应用。
2. 进入设置（Settings）。
3. 找到“开发者”（Developer）或“MCP服务器”相关设置页面。
4. 添加一个新的MCP服务器配置。配置方式通常是两种：
   • 命令行配置：提供启动服务器的命令和路径。例如：

     { "mcpServers": { "bcb-br": { "command": "python", "args": ["/你的绝对路径/bcb-br-mcp/src/server.py"], "env": { "PYTHONPATH": "/你的绝对路径/bcb-br-mcp" } } } }

   • 标准输入输出（stdio）：如果服务器设计为通过标准输入输出通信，Claude Desktop会自动管理其进程生命周期。
5. 保存配置并重启Claude Desktop。

重启后，当你新建一个对话，理论上你的Claude助手就已经具备了查询巴西央行数据的能力。你可以尝试问它：“你现在能访问巴西央行数据吗？”或者直接提出数据查询请求。

4. 开发与扩展：理解服务器内部机制

如果你不满足于仅仅使用，还想了解其内部原理，甚至进行二次开发，那么我们需要深入代码层面。虽然我无法看到该项目的具体代码，但可以基于MCP的Python SDK (mcplibrary) 和一个典型的HTTP客户端，勾勒出其核心代码结构。

4.1 核心代码结构剖析

一个基本的bcb-br-mcp服务器可能包含以下模块：

1. server.py：程序入口点。负责初始化MCP服务器，注册工具（Tools），并启动通信。

   # 示例性伪代码 import mcp from .tools import data_fetcher from .config import settings async def main(): # 1. 创建MCP服务器实例 server = mcp.Server("bcb-br-mcp") # 2. 注册工具。这里将我们自定义的`get_series_data`函数注册为一个MCP工具。 @server.list_tools() async def list_tools(): return [ mcp.Tool( name="get_bcb_series_data", description="从巴西中央银行获取指定时间序列的经济数据。", inputSchema={ "type": "object", "properties": { "series_codes": {"type": "array", "items": {"type": "integer"}, "description": "SGS序列编码列表"}, "start_date": {"type": "string", "format": "date", "description": "起始日期 (YYYY-MM-DD)"}, "end_date": {"type": "string", "format": "date", "description": "结束日期 (YYYY-MM-DD)"}, }, "required": ["series_codes"] } ), # ... 可以注册更多工具，如 search_series ] @server.call_tool() async def call_tool(name: str, arguments: dict): if name == "get_bcb_series_data": # 调用真正的业务逻辑函数 result = await data_fetcher.fetch_series_data(**arguments) return [mcp.TextContent(type="text", text=result)] # ... 处理其他工具 raise ValueError(f"未知工具: {name}") # 3. 使用标准输入输出与客户端通信 async with mcp.stdio_server() as (read_stream, write_stream): await server.run(read_stream, write_stream) if __name__ == "__main__": import asyncio asyncio.run(main())

2. tools/data_fetcher.py：核心业务逻辑层。这里封装了与BCB API交互的所有细节。

   import httpx import pandas as pd from datetime import datetime from .cache import get_cache, set_cache # 假设有缓存模块 class BCBAPIClient: BASE_URL = "https://api.bcb.gov.br/dados/serie" async def fetch_series(self, series_code: int, start_date: str, end_date: str): """获取单个序列的数据""" cache_key = f"{series_code}_{start_date}_{end_date}" cached = get_cache(cache_key) if cached: return cached url = f"{self.BASE_URL}/bcdata.sgs.{series_code}/dados" params = { "formato": "json", "dataInicial": start_date, "dataFinal": end_date } async with httpx.AsyncClient(timeout=30.0) as client: try: resp = await client.get(url, params=params) resp.raise_for_status() data = resp.json() # 数据清洗：将BCB返回的格式转换为更易读的格式 df = pd.DataFrame(data) df['data'] = pd.to_datetime(df['data'], dayfirst=True) # 注意巴西日期格式可能是dd/mm/yyyy df['valor'] = pd.to_numeric(df['valor'], errors='coerce') result = df.to_string(index=False) # 或转换为其他格式 set_cache(cache_key, result, ttl=3600) return result except httpx.HTTPStatusError as e: return f"请求API失败，状态码：{e.response.status_code}" except Exception as e: return f"发生未知错误：{str(e)}" async def fetch_multiple_series(self, series_codes: list, start_date: str, end_date: str): """并发获取多个序列的数据""" tasks = [] for code in series_codes: task = self.fetch_series(code, start_date or "1900-01-01", end_date or datetime.today().strftime('%Y-%m-%d')) tasks.append(task) results = await asyncio.gather(*tasks, return_exceptions=True) # 合并和处理结果... return combined_result

3. tools/series_registry.py：数据序列注册表。这里可能维护着一个字典，将常见的经济指标名称（如“SELIC”、“IPCA”、“Taxa de Câmbio”）映射到其SGS编码。

   SERIES_REGISTRY = { "selic": 432, # 基准利率 "ipca": 433, # 广义消费者价格指数 "igp-m": 189, # 广义市场价格指数-月度 "cambio_usd": 1, # 美元买入汇率 "pib_industrial": 24363, # 工业GDP # ... 更多映射 } def search_series_by_keyword(keyword: str): """根据关键词搜索序列""" keyword_lower = keyword.lower() results = [] for name, code in SERIES_REGISTRY.items(): if keyword_lower in name: results.append({"name": name, "code": code}) # 也可以尝试在线搜索BCB的目录（如果项目实现了更高级的搜索） return results

4. config.py和cache.py：处理配置管理和数据缓存，提升性能和可用性。

4.2 扩展功能设想

理解了基础结构后，你可以基于此项目进行扩展：

• 增加更多数据源：除了BCB SGS，巴西还有许多其他官方数据源，如IBGE（地理统计局）、ANP（国家石油局）等。可以为每个数据源编写一个类似的“客户端”模块，然后在主服务器中注册对应的工具。
• 增强数据预处理：在返回数据前，自动进行简单的计算，如计算环比、同比变化率，或数据可视化描述。
• 实现更智能的搜索：集成一个本地向量数据库，将BCB数据序列的描述文本进行嵌入（embedding），实现基于语义的相似性搜索，而不仅仅是关键词匹配。
• 添加身份验证层：虽然BCB的公共API可能不需要，但如果未来需要接入某些需要API Key的商业数据源，可以在此框架上添加安全的密钥管理。

5. 常见问题与故障排查实录

在实际部署和使用bcb-br-mcp的过程中，你可能会遇到一些典型问题。以下是我根据类似项目经验总结的排查清单。

5.1 部署与连接问题

问题1：运行python server.py时提示“ModuleNotFoundError: No module named 'mcp'”。

• 原因：Python依赖没有正确安装，或者你不在虚拟环境中。
• 解决：
  1. 确认已激活虚拟环境（命令行提示符前有(.venv)字样）。
  2. 在项目根目录下，重新运行pip install -r requirements.txt。
  3. 如果项目使用pyproject.toml，尝试pip install -e .进行可编辑模式安装。

问题2：Claude Desktop 提示“无法连接到MCP服务器”或“服务器启动失败”。

• 原因：Claude Desktop的配置有误，或者服务器进程没有正常启动。
• 解决：
  1. 检查服务器日志：首先确保你的server.py能在终端独立运行且不报错。在终端手动运行它，看是否有错误输出。
  2. 检查路径和命令：在Claude Desktop配置中，command和args的路径必须是绝对路径，并且指向正确的Python解释器和脚本。如果你的Python在虚拟环境中，command应该指向虚拟环境内的Python二进制文件（如/path/to/project/.venv/bin/python）。
  3. 检查端口冲突：如果服务器配置为监听特定端口（如8080），确保该端口没有被其他程序占用。
  4. 简化测试：尝试在配置中使用最简化的命令，排除环境变量等问题。

问题3：服务器运行正常，但Claude助手说“没有可用的工具”或无法识别数据查询指令。

• 原因：MCP工具注册可能未成功，或者Claude Desktop的缓存未更新。
• 解决：
  1. 重启Claude Desktop。有时客户端需要重启才能识别新添加的服务器。
  2. 在Claude对话中，尝试直接询问助手：“你现在有哪些可用的工具？” 一个正确配置的MCP助手会列出bcb-br-mcp提供的工具列表。
  3. 检查服务器代码中的list_tools函数，确保它正确返回了工具定义。

5.2 数据查询问题

问题4：查询数据时返回“未找到序列”或“API请求失败”。

• 原因：
  • SGS序列编码错误。
  • BCB API服务暂时不可用或URL已变更。
  • 日期格式不正确。
• 解决：
  1. 验证编码：去巴西央行官网的SGS页面，手动验证你使用的序列编码是否存在。例如，访问https://www3.bcb.gov.br/sgspub/consultarvalores/consultarValoresSeries.do?method=consultarValores（这是一个查询界面，非API）。
  2. 检查日期：确保日期格式为YYYY-MM-DD。巴西的日期表示有时是DD/MM/YYYY，但API通常接受国际标准格式。
  3. 手动测试API：用浏览器或curl命令直接访问你代码中构造的API URL，看是否能返回数据。这能帮你定位是代码问题还是网络/服务问题。
  4. 查看项目Issue：去GitHub仓库的Issues页面，看看是否有其他人遇到类似问题，或者BCB API是否有更新。

问题5：返回的数据是乱码或格式奇怪。

• 原因：BCB API返回的JSON中，日期或数字格式可能需要特殊处理（如巴西葡萄牙语的小数点逗号）。
• 解决：
  1. 在data_fetcher.py中加强数据清洗逻辑。例如，将valor字段中的"1.234,56"（字符串）转换为浮点数1234.56。
  2. 使用pandas的read_json时，注意指定date_format参数。
  3. 在返回给MCP客户端前，将数据统一转换为明确的格式（如纯文本表格、JSON数组），避免歧义。

问题6：查询速度慢，尤其是获取多年数据时。

• 原因：BCB API可能有速率限制，或者单次请求数据量过大。
• 解决：
  1. 启用缓存：这是最重要的优化。确保项目的缓存功能已开启，并为缓存设置合理的TTL（例如1小时）。对于历史数据，缓存时间可以很长。
  2. 分页或分时段请求：如果API支持，考虑将大时间范围的请求拆分成多个小请求。
  3. 异步并发：在fetch_multiple_series函数中，确保使用asyncio.gather等机制并发请求多个序列，而不是串行。

5.3 维护与更新

问题7：BCB API更新了，导致项目无法使用。

• 原因：第三方API发生变更（URL、参数、响应格式）是开源项目面临的常见挑战。
• 解决：
  1. 关注仓库：Star或Watch该GitHub项目，以便及时收到更新通知。
  2. 检查提交记录：维护者Sidney Bissoli可能已经提交了修复。拉取最新代码。
  3. 自行修复：如果你有能力，可以查看BCB官方文档，修改data_fetcher.py中的API请求逻辑，并向原项目提交Pull Request，帮助社区。
  4. 降级使用：如果只是新增功能不可用，而核心数据获取仍有效，可以暂时忽略。

问题8：我想添加一个新的经济指标，但不知道它的SGS编码。

• 解决：
  1. 最好的方法是去巴西央行SGS系统的网站，使用其搜索功能找到你需要的指标，其详情页URL或页面信息中通常会包含序列编码。
  2. 将{指标名称: 编码}这对映射添加到本地的series_registry.py文件中。
  3. 如果你认为这个指标对其他人也有用，可以考虑向原项目提交一个添加映射的PR。

这个项目体现了一个非常实用的趋势：将专业领域的实时数据能力，通过标准协议（MCP）注入到通用AI助手中，创造出垂直领域的超级生产力工具。它的成功不仅在于代码本身，更在于其精准地抓住了巴西开发者社区的一个具体需求痛点。对于其他地区或领域的开发者来说，这同样是一个绝佳的参考范例——你可以借鉴其架构，为自己关心的数据源（比如某个国家的统计局、某个行业的公开数据库）构建一个专属的MCP服务器，从而让你的AI编程伙伴变得更加强大和专业。