Tesouro Direto MCP Server

Tesouro Direto MCP 服务

一个用于集成 Tesouro Direto API 的模型上下文协议（MCP）服务实现，可通过自然语言访问巴西国债数据。

---

功能

通过兼容 MCP 的客户端使用日常语言查询市场数据、债券详情，以及搜索/筛选债券。

• MCP 工具：
  • market_data：获取国债市场的通用数据（开盘/收盘时间、状态）
  • bond_data：获取特定债券的详细信息
  • search_bonds：按类型、到期日及其他条件搜索/筛选债券
• 智能缓存：基于 API 更新时间戳的 10 分钟内存缓存，可在确保数据新鲜度的同时减少调用次数。

---

使用示例

在兼容 MCP 的客户端中，可以使用以下提示词：

• “显示所有可用的 Tesouro Direto 债券”
• “获取 IPCA+ 2029 债券的详情”
• “搜索 2045 年后到期的 IPCA 债券”
• “当前国债市场状态如何？”
• “详细分析 IPCA 债券和固定利率债券中收益率最高的前三种债券。”

---

安装

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 Tesouro Direto MCP 服务：

npx -y @smithery/cli install @AtilioA/tesouro-direto-mcp --client claude

通过 npm 安装

MCP 客户端配置示例 JSON（Cursor/Claude）

使用 npx，将以下内容添加到 ~/.cursor/mcp.json；如果使用 Claude 的桌面应用，则添加到 claude_desktop_config.json：

{
    "mcpServers": {
        "tesouro-direto": {
            "command": "npx",
            "args": [
                "-y",
                "tesouro-direto-mcp"
            ],
            "env": {
                "USE_MCP_CACHE": "true"
            }
        }
    }
}

---

从源代码构建

# Clone the repository
git clone https://github.com/AtilioA/tesouro-direto-mcp.git
cd tesouro-direto-mcp

# Install dependencies
pnpm install

# Build the project
pnpm run build

构建后，可以直接运行 MCP 服务：

node dist/index.js

也可以将其用于任何兼容 MCP 的客户端（例如 MCP Inspector）：

npx @modelcontextprotocol/inspector dist/index.js

---

工具

market_data

获取通用市场数据，包括开盘/收盘时间和当前状态。

bond_data

通过债券代码获取特定债券的详细信息。

search_bonds

按类型（SELIC、IPCA、PREFIXADO）、到期日等条件搜索和筛选债券。

---

环境变量

变量	描述	默认值
USE_MCP_CACHE	启用 API 响应的内存缓存	true

在环境变量中或 MCP 客户端配置中设置这些变量。

---

项目结构

src/
├── api/         # API client for Tesouro Direto
│   └── tesouroDireto.ts
├── cache/       # Caching implementation
│   └── apiCache.ts
├── resources/   # MCP resources implementation
│   └── index.ts
├── tools/       # MCP tools implementation
│   ├── bondData.ts
│   ├── marketData.ts
│   └── searchBonds.ts
├── types/       # Type definitions
│   └── index.ts
├── utils/       # Utility functions
│   ├── errorHandler.ts
│   └── logger.ts
├── client.ts    # Example MCP client
├── index.ts     # Entry point
└── server.ts    # MCP server implementation

---

可用脚本

• pnpm run build / npm run build：构建项目
• pnpm start / npm start：启动服务
• pnpm run dev / npm run dev：以开发模式启动服务并自动重新加载

---

贡献

欢迎贡献！请在 GitHub 上提交议题或拉取请求。

---

许可证

本项目采用 GNU Affero 通用公共许可证 v3.0。详情请参阅 LICENSE 文件。