https://github.com/atilioa/tesouro-direto-mcp
🗣️ Query Brazilian treasury bond data with natural language
https://github.com/atilioa/tesouro-direto-mcp
mcp mcp-server tesouro-direto treasury-bonds
Last synced: 5 months ago
JSON representation
🗣️ Query Brazilian treasury bond data with natural language
- Host: GitHub
- URL: https://github.com/atilioa/tesouro-direto-mcp
- Owner: AtilioA
- License: agpl-3.0
- Created: 2025-04-14T19:04:15.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-05-15T18:56:18.000Z (6 months ago)
- Last Synced: 2025-06-18T09:50:44.632Z (5 months ago)
- Topics: mcp, mcp-server, tesouro-direto, treasury-bonds
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/tesouro-direto-mcp
- Size: 78.1 KB
- Stars: 3
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- toolsdk-mcp-registry - ✅ tesouro-direto-mcp - time access to Brazil's Treasury Direct bond market data, enabling users to retrieve market status, search bonds by type and maturity date, and access detailed information for investment analysis. (3 tools) (node) (Finance & Fintech / How to Submit)
- toolsdk-mcp-registry - ✅ tesouro-direto-mcp - time access to Brazil's Treasury Direct bond market data, enabling users to retrieve market status, search bonds by type and maturity date, and access detailed information for investment analysis. (3 tools) (node) (Finance & Fintech)
README
# Tesouro Direto MCP Server
[](https://smithery.ai/server/@AtilioA/tesouro-direto-mcp)
[](https://www.npmjs.com/package/tesouro-direto-mcp)
[](LICENSE)
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](https://smithery.ai/server/@AtilioA/tesouro-direto-mcp):
```bash
npx -y @smithery/cli install @AtilioA/tesouro-direto-mcp --client claude
```
### Installing via npm
### Example JSON for MCP client configuration (Cursor/Claude)
With [npx](https://docs.npmjs.com/cli/commands/npx), add this to your `~/.cursor/mcp.json`, or `claude_desktop_config.json` if you are using its desktop app:
```json
{
"mcpServers": {
"tesouro-direto": {
"command": "npx",
"args": [
"-y",
"tesouro-direto-mcp"
],
"env": {
"USE_MCP_CACHE": "true"
}
}
}
}
```
---
### Building from source
```bash
# 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:
```bash
node dist/index.js
```
Or use it with any MCP-compatible client (e.g., MCP Inspector):
```bash
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 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](https://github.com/AtilioA/tesouro-direto-mcp).
---
## License
This project is licensed under the GNU Affero General Public License v3.0. See the [LICENSE](LICENSE) file for details.