Finance MCP 💰

Um assistente financeiro conversacional construído com Python, utilizando MCP (Model Context Protocol) para integrar um LLM (Gemini) a dados e regras de negócio bem definidas.

O objetivo do projeto é explorar arquitetura moderna para aplicações com LLMs, indo além de um simples chatbot, separando claramente:

• raciocínio (modelo)
• dados e ações (tools)
• protocolo de comunicação (MCP)

🧠 O que é MCP (Model Context Protocol)?

O MCP é um protocolo que padroniza a comunicação entre modelos de linguagem e sistemas externos.

Neste projeto:

• O LLM decide o que fazer
• O MCP Server executa como fazer
• As tools expõem dados financeiros de forma segura e estruturada

Isso permite criar assistentes:

• previsíveis
• testáveis
• escaláveis
• desacoplados do modelo

✨ Funcionalidades

• 📊 Listagem de contas e saldos
• 🧾 Consulta de transações com filtros
• 📅 Resumo financeiro mensal
• 📈 Previsão simples de fluxo de caixa
• 🚨 Detecção de despesas anômalas
• 💬 Interface em CLI com linguagem natural
• ⏱️ Inferência automática de datas (este mês, mês passado, etc.)

Os dados são mockados e mantidos em memória (MVP).

🏗️ Arquitetura

Usuário (CLI)
│
▼
Gemini (LLM)
│  decide quais tools usar
▼
MCP Client
│
▼
MCP Server (Python)
│
├── list_accounts
├── list_transactions
├── monthly_summary
├── cashflow_forecast
└── detect_anomalies

🛠️ Tecnologias

• Python 3.10+
• MCP (Model Context Protocol)
• Google Gemini API
• python-dotenv
• AsyncIO

📁 Estrutura do Projeto

finance_mcp/
├── .env
├── .gitignore
├── requirements.txt
├── finance_mcp_server.py
├── gemini_finance_client.py
└── README.md

⚙️ Instalação

1️⃣ Clone o repositório

git clone https://github.com/seu-usuario/finance-mcp.git
cd finance-mcp

2️⃣ Crie e ative um ambiente virtual

python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux / Mac
source .venv/bin/activate

3️⃣ Instale as dependências

pip install -r requirements.txt

🔐 Configuração de Ambiente

Crie um arquivo .env na raiz do projeto:

GEMINI_API_KEY=sua_api_key_aqui
GEMINI_MODEL=gemini-2.5-flash
MCP_URL=http://localhost:8000/mcp

⚠️ Nunca versione o arquivo .env.

▶️ Como Executar

1️⃣ Inicie o servidor MCP

python finance_mcp_server.py

2️⃣ Em outro terminal, inicie o client

python gemini_finance_client.py

💬 Exemplos de Perguntas

Qual o saldo das minhas contas?
Quanto gastei com alimentação este mês?
Me dá um resumo financeiro do mês passado
Qual foi meu saldo líquido este mês?
Quanto eu economizei no mês passado?

📌 Status do Projeto

• ✅ MCP Server funcional
• ✅ Integração com LLM
• ✅ Inferência temporal automática
• ✅ Arquitetura desacoplada
• ⛔ Persistência (em progresso)
• ⛔ Interface gráfica (futuro)

🚀 Próximos Passos

• Persistência com SQLite
• Metas de economia mensais
• Dashboard web (Streamlit ou FastAPI)
• Autenticação
• Suporte a LLM local (Ollama)

👤 Autor

Francisco Cauan Victor da Silva Gonçalves Engenharia de Software • IA Aplicada • Python

Projeto desenvolvido com foco em aprendizado, arquitetura e boas práticas para aplicações modernas com LLMs.