Tesouro Direto MCP Server

Tesouro Direto MCP Server

Uma implementação de servidor Model Context Protocol (MCP) para integração com a API do Tesouro Direto, permitindo acesso em linguagem natural aos dados de títulos públicos brasileiros.

---

Recursos

Consulte dados de mercado, detalhes de títulos e pesquise/filtre títulos usando linguagem cotidiana por meio de clientes compatíveis com MCP.

• Ferramentas MCP:
  • market_data: Recupera dados gerais do mercado de títulos do Tesouro (horários de abertura/fechamento, status)
  • bond_data: Obtém informações detalhadas sobre um título específico
  • search_bonds: Pesquisa/filtra títulos por tipo, vencimento e outros critérios
• Cache inteligente: cache em memória de 10 minutos baseado nos carimbos de atualização da API para reduzir chamadas, garantindo a atualidade dos dados.

---

Exemplo de uso

Em um cliente compatível com MCP, você pode usar os seguintes prompts:

• "Mostre todos os títulos do Tesouro Direto disponíveis"
• "Obtenha detalhes do título IPCA+ 2029"
• "Pesquise títulos IPCA com vencimento após 2045"
• "Qual é o status atual do mercado de títulos do Tesouro?"
• "Forneça uma análise detalhada dos três principais títulos com os maiores rendimentos, tanto para títulos IPCA quanto para títulos de taxa fixa."

---

Instalação

Instalando via Smithery

Para instalar o Tesouro Direto MCP Server para Claude Desktop automaticamente via Smithery:

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

Instalando via npm

Exemplo de JSON para configuração do cliente MCP (Cursor/Claude)

Com npx, adicione isto ao seu ~/.cursor/mcp.json, ou claude_desktop_config.json se você estiver usando o aplicativo de desktop:

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

---

Compilando a partir do código-fonte

# 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

Você pode executar o servidor MCP diretamente após a compilação:

node dist/index.js

Ou use-o com qualquer cliente compatível com MCP (ex.: MCP Inspector):

npx @modelcontextprotocol/inspector dist/index.js

---

Ferramentas

market_data

Recupera dados gerais do mercado, incluindo horários de abertura/fechamento e status atual.

bond_data

Obtém informações detalhadas de um título específico pelo seu código.

search_bonds

Pesquisa e filtra títulos por tipo (SELIC, IPCA, PREFIXADO), data de vencimento e mais.

---

Variáveis de ambiente

Variável	Descrição	Padrão
USE_MCP_CACHE	Habilita o cache em memória para respostas da API	true

Defina estas variáveis no seu ambiente ou na configuração do seu cliente MCP.

---

Estrutura do projeto

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 disponíveis

• pnpm run build / npm run build: Compila o projeto
• pnpm start / npm start: Inicia o servidor
• pnpm run dev / npm run dev: Inicia o servidor em modo de desenvolvimento com recarga automática

---

Contribuição

Contribuições são bem-vindas! Abra uma issue ou envie um pull request no GitHub.

---

Licença

Este projeto é licenciado sob a GNU Affero General Public License v3.0. Consulte o arquivo LICENSE para obter detalhes.