Tesouro Direto MCP Server

Servidor MCP de Tesouro Direto

Una implementación de servidor del Model Context Protocol (MCP) para integrarse con la API de Tesouro Direto, que permite el acceso en lenguaje natural a los datos de los títulos públicos brasileños.

---

Características

Consulta datos de mercado, detalles de títulos y busca/filtra títulos usando lenguaje cotidiano a través de clientes compatibles con MCP.

• Herramientas MCP:
  • market_data: Recupera datos generales del mercado de títulos públicos (horarios de apertura/cierre, estado)
  • bond_data: Obtén información detallada sobre un título específico
  • search_bonds: Busca/filtra títulos por tipo, vencimiento y otros criterios
• Caché inteligente: caché en memoria de 10 minutos basada en las marcas de tiempo de actualización de la API para reducir llamadas y garantizar la frescura de los datos.

---

Ejemplo de uso

En un cliente compatible con MCP, puedes usar los siguientes comandos:

• "Mostrar todos los títulos disponibles de Tesouro Direto"
• "Obtener detalles del título IPCA+ 2029"
• "Buscar títulos IPCA que vencen después de 2045"
• "¿Cuál es el estado actual del mercado de títulos públicos?"
• "Proporciona un análisis detallado de los tres títulos con mayores rendimientos, tanto para títulos IPCA como para títulos de tasa fija."

---

Instalación

Instalación mediante Smithery

Para instalar Tesouro Direto MCP Server para Claude Desktop automáticamente a través de Smithery:

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

Instalación mediante npm

Ejemplo de JSON para configuración del cliente MCP (Cursor/Claude)

Con npx, agrega esto a tu ~/.cursor/mcp.json, o claude_desktop_config.json si estás usando su aplicación de escritorio:

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

---

Compilación desde el código fuente

# 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

Puedes ejecutar el servidor MCP directamente después de compilar:

node dist/index.js

O úsalo con cualquier cliente compatible con MCP (por ejemplo, MCP Inspector):

npx @modelcontextprotocol/inspector dist/index.js

---

Herramientas

market_data

Recupera datos generales del mercado, incluidos horarios de apertura/cierre y estado actual.

bond_data

Obtén información detallada de un título específico por su código.

search_bonds

Busca y filtra títulos por tipo (SELIC, IPCA, PREFIXADO), fecha de vencimiento y más.

---

Variables de entorno

Variable	Descripción	Valor por defecto
USE_MCP_CACHE	Habilita la caché en memoria para las respuestas de la API	true

Configúralas en tu entorno o en la configuración de tu cliente MCP.

---

Estructura del proyecto

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

---

Scripts disponibles

• pnpm run build / npm run build: Compilar el proyecto
• pnpm start / npm start: Iniciar el servidor
• pnpm run dev / npm run dev: Iniciar el servidor en modo de desarrollo con recarga automática

---

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, abre un issue o envía un pull request en GitHub.

---

Licencia

Este proyecto está licenciado bajo la Licencia Pública General Affero de GNU v3.0. Consulta el archivo LICENSE para más detalles.