What is Tesouro Direto Mcp

tesouro-direto-mcp is an MCP server implementation that allows users to query Brazilian treasury bond data using natural language. It integrates with the Tesouro Direto API to provide accessible financial information.

Use cases

Use cases include retrieving current market status, getting details about specific bonds, and analyzing bond yields based on user-defined criteria.

How to use

To use tesouro-direto-mcp, install it via npm or build it from source. Configure your MCP client to connect to the server and use natural language prompts to query bond data.

Key features

Key features include querying market data, retrieving detailed bond information, and searching/filtering bonds by various criteria. It also features smart caching to enhance performance.

Where to use

tesouro-direto-mcp can be used in financial applications, investment platforms, and any software that requires 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 bond
  • search_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

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 project
• pnpm start / npm start: Start the server
• pnpm 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 LICENSE file for details.