💰 Asistente de Finanzas Personales — MCP + Gemini

Un asistente de finanzas con IA que te permite preguntar sobre tus gastos en lenguaje natural. Está construido con el Model Context Protocol (MCP) para conectar el Gemini de Google con herramientas reales — una base de datos SQL, modelos de previsión y detección de anomalías — en lugar de un chatbot programado que solo sabe hablar.

🔗 Demo en vivo: mcp-finance-assistant-z6txg3k6xparsajcsvftrr.streamlit.app

Lo que hace

Pregúntale cosas como:

• "¿Cuánto gasté en comida este mes?"

• "Compara mis gastos de agosto con los de julio"

• "Añade un gasto de 250 en Uber al aeropuerto" — infiere la categoría por sí mismo

• "¿Cuánto gastaré en comida el próximo mes?" — previsión real con ML, no una suposición

También proactivamente señala los gastos inusuales en cuanto se carga la página, sin que se le pregunte.

Related MCP server: Expense Tracker MCP Server

¿Por qué MCP?

La mayoría de las demos de asistentes financieros con IA preprograman las respuestas del chatbot o acoplan un LLM a datos estáticos. Este proyecto, en cambio, construye un servidor MCP real: una forma estandarizada (introducida por Anthropic) para que un modelo de IA descubra y llame a herramientas reales. Gemini lee las herramientas disponibles, decide cuál o cuáles necesita, las llama a través del protocolo MCP y razona sobre los resultados reales. Es el mismo patrón que usan los sistemas de agentes de IA en producción, no una simulación de juguete.

Arquitectura

User question → Streamlit UI → Gemini (decides which tool to call)
                                      ↓
                          MCP Server (server.py)
                                      ↓
                          SQLite Database (real transaction data)
                                      ↓
                     Tool result → back to Gemini → plain-English answer

Para solicitudes de varios pasos (como añadir un gasto sin categoría), Gemini encadena varias llamadas a herramientas: primero obtiene las categorías existentes, luego infiere la correcta y, por último, añade el gasto, hasta 3 pasos por pregunta.

Características

• 7 herramientas MCP: consultar totales, comparar meses, listar gastos recientes, añadir gastos, obtener categorías, prever gastos y detectar anomalías

• ML real, no reglas: forecast_next_month utiliza LinearRegression de scikit-learn sobre tendencias históricas; detect_anomaly usa un modelo no supervisado IsolationForest en lugar de un umbral predefinido

• Categorización inferida por LLM: describe un gasto en lenguaje natural y Gemini elige la categoría correcta por sí solo, encadenando llamadas a herramientas para hacerlo

• Información proactiva: comprobaciones automáticas de anomalías al cargar la página, sin necesidad de preguntar

• Memoria de conversación: las preguntas de seguimiento entienden el contexto de la conversación anterior en el chat

• Datos reales: más de 240 registros de transacciones reales, incluidos 231 importados y preparados de un dataset público de gastos personales de Kaggle

• Prácticas de producción: manejo completo de errores y validación de entrada en cada herramienta, registro estructurado (app.log) y una suite de pytest con 8 pruebas que veren los cálculos frente a datos conocidos

Stack tecnológico

Python · MCP SDK · Google Gemini (google-genai) · SQLite · scikit-learn · Streamlit · pytest

Ejecutarlo localmente

git clone https://github.com/srushtikochare/mcp-finance-assistant
cd mcp-finance-assistant
pip install -r requirements.txt

Crea un archivo .env:

GOOGLE_API_KEY=your_api_key_here

A continuación, ejecuta:

streamlit run app.py

Ejecutar las pruebas

pytest test_server.py -v

8 pruebas que cubren sumas correctas, manejo de errores y comportamiento de las herramientas ML — todas pasan.

Un desafío real que encontré

La estructura del SDK de Python de MCP había cambiado desde que se escribió la mayoría de la documentación disponible — la clase que esperaba (FastMCP) no existía en la versión instalada. En lugar de adivinar, inspeccioné el paquete real instalado (dir(mcp.server)) para encontrar la clase correcta actual (MCPServer) y su superficie de API. Depurar contra una biblioteca en evolución con documentación incompleta, en lugar de una estable y orientada a tutoriales, fue la parte más valiosa de la creación de esto.

Próximos pasos posibles

• Soporte multiusuario con inicios de sesión individuales

• Subida de recibos/estados de cuenta con OCR para el registro automático de gastos

• Lógica de reintentos con backoff para la resiliencia de las API externas

Autor

Srushti Kochare — B.Tech en Inteligencia Artificial y Ciencia de Datos, YCCE Nagpur