Tesouro Direto MCP

🚀 Treasury Direct MCP Server

A Model Context Protocol (MCP) server implementation for integrating with the Tesouro Direto API, providing natural language access to Brazilian Treasury bond data through MCP-compatible clients.

🚀 Quick Start

This is a Model Context Protocol (MCP) server implementation integrating with the Tesouro Direto API. It offers natural - language access to Brazilian Treasury bond data via MCP - compatible clients.

✨ Features

Query market data, bond details, and search/filter bonds by type, maturity date, and other criteria using everyday language.

• MCP Tools:
  • market_data: Retrieve general Treasury bond market data (opening/closing times, status).
  • bond_data: Get detailed information about specific bonds.
  • search_bonds: Search/filter bonds by type, maturity date, and other criteria.
• Intelligent Caching: A 10 - minute in - memory cache based on API update timestamps to reduce calls and ensure data freshness.

💻 Usage Examples

Basic Usage

In an MCP - compatible client, you can use the following prompts:

• "Show all available Treasury Direct bonds."
• "Get the details of the IPCA+2029 bond."
• "Search for IPCA bonds maturing after 2045."
• "What is the current status of the Treasury bond market?"
• "Provide a detailed analysis of the top three bonds with the highest yields (including IPCA and fixed - rate bonds)."

📦 Installation

Install via npm

Example JSON Configuration File (for Cursor/Claude)

Use npx and add the following to ~/.cursor/mcp.json or claude_desktop_config.json:

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

Build from Source Code

# 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

📚 Documentation

Tools

• market_data: Used to obtain general Treasury bond market data, including opening and closing times and market status.
• bond_data: Used to get detailed information about specific bonds, such as issuance details and yields.
• search_bonds: Allows searching or filtering bonds by type, maturity date, and other criteria.

Environment Variables

Project Structure

Treasury-Direct-MCP-Server
├── src/
│   ├── market_data.js       # Module for handling market data
│   ├── bond_data.js         # Module for getting bond details
│   └── search_bonds.js     # Module for searching and filtering bonds
├── package.json           # Project dependencies and script configuration
└── LICENSE                # License file

Available Scripts

🤝 Contribution

Contributions are welcome! Please visit GitHub to see how to get involved.

📄 License

This project is licensed under the GNU Affero General Public License v3.0. See the LICENSE file for details.