orcamento
💬 Orçamento Conversacional — Gestão financeira pessoal por linguagem natural, direto no Telegram
Registre despesas como quem manda mensagem para um amigo — sem formulário, sem planilha. Um agente de IA (Google Gemini, orquestrado pelo Nanobot) interpreta a mensagem, extrai valor, categoria, método de pagamento e data, e grava tudo em um banco PostgreSQL. Quando você quiser, ele te devolve um relatório em PDF com dashboard completo ou gera recomendações financeiras personalizadas para economizar.
Você: Gastei 35 no almoço hoje, no pix
Bot: Registrado: R$ 35,00 em alimentação (almoço, no pix).Índice
Related MCP server: TeleMCP
Visão Geral
Este é um protótipo de pesquisa que investiga a viabilidade de uma interface 100% conversacional para controle financeiro pessoal, com foco em jovens adultos (18–29 anos). A ideia central: em vez de adaptar o usuário à estrutura de um app, o sistema se adapta à forma como a pessoa já fala naturalmente sobre seus gastos.
Todo o pipeline roda em containers Docker — não é preciso instalar Python, Postgres ou o Nanobot na máquina. O modelo de linguagem (Google Gemini) roda na nuvem, então não há download nem execução de modelo local.
Funcionalidades
Funcionalidade | Descrição |
📝 Registro por linguagem natural | Extrai valor, descrição, categoria, método de pagamento e data de uma mensagem comum, sem campos ou comandos estruturados |
🔍 Consultas em linguagem natural | "Quanto gastei em alimentação esse mês?", "Quanto gastei entre 01/08 e 15/08?" |
📊 Resumo por categoria | Total e participação percentual de cada categoria num período |
📄 Relatório em PDF (dashboard, 3 páginas) | Enviado direto no Telegram: (1) panorama por categoria, (2) panorama por método de pagamento, (3) tabela detalhada de gastos por dia |
💡 Recomendações financeiras | "Como posso economizar este mês?", "Onde eu poderia economizar entre 01/08 e 31/08?" — 2 a 4 dicas práticas geradas a partir dos gastos do período, só texto no chat |
Arquitetura

Camada | Tecnologia | Papel |
Canal | Telegram Bot API | Entrada e saída das mensagens |
Orquestração | Conecta canal, modelo e ferramentas | |
Modelo de linguagem | Google Gemini (API) | Interpretação e geração de respostas |
Ferramentas | Protocolo MCP, Python | Regras de negócio (registro, consulta, relatório, recomendações) |
Persistência | PostgreSQL | Armazenamento estruturado |
Geração de PDF | ReportLab + Matplotlib | Dashboard do relatório |
Empacotamento | Docker Compose | Orquestra os containers |
O servidor de ferramentas roda dentro do container do Nanobot, via stdio, em um ambiente Python isolado (/opt/mcpvenv) — necessário porque o SDK mcp usado pelas ferramentas conflita em versão com o exigido pelo próprio nanobot-ai. Detalhes em Documentação Técnica.
Requisitos
Docker e Docker Compose (Docker Desktop no Windows/Mac, Docker Engine no Linux) — é a única dependência real
Uma conta no Telegram, para criar o bot
Uma chave de API do Google Gemini (gratuita, sem cartão de crédito — free tier cobre o uso deste projeto)
Não precisa instalar Python, Postgres ou o Nanobot separadamente — tudo roda em container.
Como Executar
# 1. Copie o modelo de variáveis de ambiente
cp .env.example .env
# 2. Edite o .env com seu TELEGRAM_TOKEN e GEMINI_API_KEY
# (veja como conseguir os dois na Documentação Técnica)
# 3. Suba tudo
make up
# equivalente: docker compose up -d --build
# 4. Confira se os dois serviços estão de pé
make ps
# equivalente: docker compose psProcure seu bot no Telegram pelo username criado no BotFather e mande uma mensagem. O passo a passo completo — de onde tirar o token do bot e a chave do Gemini até o troubleshooting de cada erro comum — está na Documentação Técnica.
Comandos
Atalhos definidos no Makefile (opcional — todo comando make tem o docker compose equivalente ao lado, caso você não tenha make instalado, comum no Windows fora do WSL).
| Equivalente Docker Compose | O que faz |
|
| Constrói as imagens (se necessário) e sobe tudo em segundo plano |
|
| Para os containers, mantendo os dados do banco |
|
| Reinicia só o Nanobot (após mudar |
|
| Acompanha os logs do Nanobot em tempo real ( |
|
| Mostra o status dos containers |
|
| Reconstrói as imagens sem subir os containers |
|
| ⚠️ Para tudo e apaga os volumes (dados do Postgres inclusive) |
|
| Abre um shell |
Casos que não têm atalho no Makefile e usam docker compose direto:
Comando | Quando usar |
| Depois de editar código Python em |
| Depois de editar só |
| Ver logs de todos os containers, não só o Nanobot |
Estrutura do Projeto
orcamento-conversacional/
├── docker-compose.yml # Orquestra os containers postgres + nanobot
├── Makefile # Atalhos dos comandos acima
├── requirements.txt # Dependências Python do servidor MCP
├── .env.example # Modelo de variáveis de ambiente
│
├── db/
│ ├── schema.sql # Schema para instalação nova (banco vazio)
│ ├── migration_002_metodo_pagamento.sql # Migração segura para bancos já existentes
│ └── connection.py # Pool de conexão com o Postgres
│
├── mcp_server/ # Ferramentas do agente + geração de relatório PDF e recomendações
│ ├── expense_tools.py # As 5 tools: registrar, listar, resumir, gerar PDF, gerar recomendação
│ ├── dashboard_builder.py # Página 1 do relatório (panorama por categoria)
│ ├── dashboard_pagamento.py # Página 2 do relatório (panorama por método de pagamento)
│ ├── dashboard_gastos_dia.py# Página 3 do relatório (tabela de gastos por dia)
│ ├── dash_style.py # Paleta de cores, nomes e ícones (categorias/métodos)
│ ├── icons.py # Ícones vetoriais desenhados no PDF
│ └── Dockerfile
│
└── nanobot_config/
├── config.docker.json # Config ativa quando roda via Docker
├── config.json # Config para instalação local (sem Docker)
├── SOUL.md # Instruções de comportamento do agente
├── AGENTS.md # Regras gerais complementares
└── DockerfileDetalhamento completo de cada arquivo, da arquitetura interna e do schema do banco: Documentação Técnica.
Documentação Técnica
Este README cobre o essencial para rodar o projeto. Para o passo a passo detalhado — incluindo:
Como conseguir o token do bot no BotFather (com prints do que esperar)
Como conseguir e configurar a chave da API do Gemini
Lista completa de problemas comuns e como resolver cada um
Detalhamento de arquitetura (por que o MCP roda num venv isolado, por que existem dois arquivos de config do Nanobot)
Instalação local sem Docker
Referência de cada ferramenta (tool) do agente
veja DOCUMENTACAO_TECNICA.md.
Licença
Distribuído sob a licença definida em LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Log expenses, receipts and mileage from chat: auto-categorise, split VAT, summarise, export, rebill.
Log expenses, receipts and mileage from chat: auto-categorise, split VAT, summarise, export, rebill.
Track expenses from your AI chat: log, categorize, monthly CSV reports. All data is local.
Expense ledger for AI assistants: record receipts line by line, ask what you spent, export anytime.
Related MCP Servers
- AlicenseBqualityCmaintenanceEnables LLMs to send notifications and receive responses via Telegram.24MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to search and act on Telegram conversations, groups, channels, files, and links, with semantic search, AI-powered knowledge extraction, human-in-the-loop approvals, and PostgreSQL/pgvector persistence.Apache 2.0
- AlicenseNot gradedqualityAmaintenanceEnables running coding-agent sessions 24/7 from Telegram, with two-way voice notes, persistent memory across restarts, live tool-call progress, scheduling, and permission approvals.MIT
- AlicenseNot gradedqualityBmaintenanceConnects Claude, ChatGPT, and Codex to a Telegram bot so they can message the user, send files, ask questions and wait for replies, and read connected groups or permitted personal chats, including replying as the user when allowed.5MIT