tesouro-direto-mcp
If you are the rightful owner of tesouro-direto-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
A Model Context Protocol (MCP) server implementation for integrating with the Tesouro Direto API, enabling natural language access to Brazilian treasury bond data.
Tesouro Direto MCP Server
A Model Context Protocol (MCP) server implementation for integrating with the Tesouro Direto API, enabling natural language access to Brazilian treasury bond data.
Features
Query market data, bond details, and search/filter bonds using everyday language through MCP-compatible clients.
- MCP tools:
market_data: Retrieve general treasury bond market data (opening/closing times, status)bond_data: Get detailed information about a specific bondsearch_bonds: Search/filter bonds by type, maturity, and other criteria
- Smart caching: 10-minute in-memory cache based on API update timestamps to reduce calls while ensuring data freshness.
Example usage
In a MCP-compatible client, you can use the following prompts:
- "Show all available Tesouro Direto bonds"
- "Get details for the bond IPCA+ 2029"
- "Search for IPCA bonds maturing after 2045"
- "What is the current treasury bond market status?"
- "Provide a detailed analysis of the top three bonds with the highest yields for both IPCA and fixed-rate bonds."
Installation
Installing via Smithery
To install Tesouro Direto MCP Server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @AtilioA/tesouro-direto-mcp --client claude
Installing via npm
Example JSON for MCP client configuration (Cursor/Claude)
With npx, add this to your ~/.cursor/mcp.json, or claude_desktop_config.json if you are using its desktop app:
{
"mcpServers": {
"tesouro-direto": {
"command": "npx",
"args": [
"-y",
"tesouro-direto-mcp"
],
"env": {
"USE_MCP_CACHE": "true"
}
}
}
}
Building from source
# 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
You can run the MCP server directly after building:
node dist/index.js
Or use it with any MCP-compatible client (e.g., MCP Inspector):
npx @modelcontextprotocol/inspector dist/index.js
Tools
market_data
Retrieve general market data, including opening/closing times and current status.
bond_data
Get detailed information for a specific bond by its code.
search_bonds
Search and filter bonds by type (SELIC, IPCA, PREFIXADO), maturity date, and more.
Environment variables
| Variable | Description | Default |
|---|---|---|
USE_MCP_CACHE | Enable the in-memory cache for API responses | true |
Set these in your environment or in your MCP client configuration.
Project structure
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
Available scripts
pnpm run build/npm run build: Build the projectpnpm start/npm start: Start the serverpnpm run dev/npm run dev: Start the server in development mode with auto-reload
Contributing
Contributions are welcome! Please open an issue or submit a pull request on GitHub.
License
This project is licensed under the GNU Affero General Public License v3.0. See the file for details.
