💰 Assistente de Finanças

Assistente inteligente de finanças para grupos utilizando IA generativa, arquitetura MCP (Model Context Protocol), integração com Gemini LLM, banco de dados MySQL e interface conversacional construída com Streamlit.

Projeto desenvolvido como portfólio técnico para demonstrar habilidades em AI Agents, LLM Engineering, Arquitetura Backend, Integração de Dados e Design de Software.

Grupos que compartilham despesas — como famílias, repúblicas ou times — frequentemente perdem o controle dos gastos por falta de uma forma simples de consultar e entender os dados financeiros. Planilhas são difíceis de navegar e dashboards exigem que o usuário saiba onde clicar.

Este assistente permite que qualquer pessoa do grupo faça perguntas em linguagem natural como "Quanto gastamos em janeiro?" ou "De quanto foram os nossos gastos com leite este mês?" e receba respostas claras e instantâneas — sem precisar abrir uma planilha ou montar um filtro.

Este projeto demonstra a construção de um Agente de IA completo, capaz de responder perguntas sobre gastos financeiros utilizando dados reais armazenados em banco de dados.

O sistema integra:

• 🤖 Large Language Model (Google Gemini)
• 🧠 Agente inteligente para interpretação das perguntas
• 🔌 MCP Server para acesso estruturado aos dados
• 🗄️ Banco de dados MySQL local (administrado via MySQL Workbench)
• 🎨 Interface conversacional com Streamlit

• Construção de AI Agent end-to-end
• Integração entre LLM e Banco de Dados via MCP (Model Context Protocol)
• Arquitetura MCP com Tool Calling
• Separação clara entre camadas da aplicação
• Organização profissional de projeto Python
• Boas práticas de engenharia de software

Clique para ver a demo

Fluxo de comunicação: Do input do usuário em linguagem natural à execução de Tools SQL via protocolo MCP.

.
├── app
├── assets
├── database
├── docs
├── llm
├── mcp_server
├── shared
├── tests
└── utils

O servidor MCP expõe ferramentas específicas que permitem ao LLM interagir com o banco de dados de forma segura. Abaixo estão as capacidades implementadas em mcp_server/tools/:

• Raciocínio do Agente: O sistema utiliza uma abordagem de Chain of Thought (Cadeia de Pensamento), onde o agente identifica a intenção do usuário, extrai entidades e decide qual Tool MCP é necessária para buscar os dados.

• Engenharia de Prompt: Implementação de técnicas de Few-Shot Prompting e instruções de sistema (System Instructions) para garantir que o LLM mantenha o foco financeiro e formate as respostas com precisão.

• Protocolo MCP: A escolha pelo Model Context Protocol garante que a lógica de acesso aos dados (SQL) esteja desacoplada da lógica do modelo, facilitando a troca de provedores de LLM no futuro.

• Google Gemini
• MCP (Model Context Protocol)
• Prompt Engineering

• Streamlit 1.30+
• Custom CSS

• Python 3.13+
• MySQL Connector/Python
• MySQL 8.0

• Pytest
• Python-Dotenv
• Makefile automation

• Separação entre Agent, MCP Server e Database Layer
• Uso de Tools MCP para evitar acesso direto do LLM ao banco
• Cache do agente com st.cache_resource
• Arquitetura modular preparada para múltiplos modelos LLM
• Organização orientada à escalabilidade e manutenção

git clone https://github.com/LuGodoy/finance-agent-mcp.git
cd finance-agent-mcp

make install

Esse comando irá criar o ambiente virtual .venv e instalar todas as dependências necessárias.

make env

Edite o arquivo .env gerado e preencha-o com suas credenciais:

GEMINI_API_KEY=sua_chave_aqui

DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=sua_senha
DB_NAME=personal_finance
TABLE_NAME=transactions

make run

A aplicação estará disponível em http://localhost:8501.

make mcp

make test

Este projeto está em desenvolvimento ativo. Próximas evoluções planejadas:

• Suporte Multi-LLM, integrando outras APIs (OpenAI GPT-4o, Claude 3.5 Sonnet e Groq) para permitir a escolha do modelo via configuração.
• Novas MCP Tools para análises mais avançadas
• Migração das queries SQL puras para SQLAlchemy (uso de um ORM como o SQLAlchemy ajudaria na sanitização de queries e na prevenção de SQL Injection)
• Suporte a múltiplos grupos de despesas
• Autenticação de usuários
• Testes de integração para as MCP Tools
• Dashboard estatístico com visualização gráfica das despesas (ex: total mensal, categorias mais frequentes, evolução ao longo do tempo)
  • Stack tecnológica planejada: Plotly + Streamlit

Este erro ocorre quando o serviço MySQL não está em execução. Utilize o comando de acordo com o seu sistema operacional:

 macOS (via Homebrew)

brew services start mysql
# ou, para reiniciar:
brew services restart mysql

🐧 Linux

sudo systemctl start mysql
# ou, para reiniciar:
sudo systemctl restart mysql

⊞ Windows (PowerShell como Administrador)

net start mysql

• Verifique se a chave Gemini está correta no .env
• Confirme que tem créditos disponíveis na API

Luciene Godoy
AI Agents | Data Science | Software Engineering | Matemática

Stack: Python • MCP • Google Gemini • MySQL • Streamlit

Este projeto foi desenvolvido para fins educacionais e demonstração de portfólio.