MCP Gastos
Servidor MCP (Model Context Protocol) para la gestión de gastos personales mediante un archivo CSV. Construido con FastMCP, este proyecto permite a agentes de IA agregar, consultar y analizar gastos de manera estructurada.
🚀 Características
- Tool:
agregar_gasto- Añade nuevos gastos al registro CSV - Resource:
resource://gastos- Consulta gastos formateados para consumo de LLMs - Prompt: Plantilla para generar resúmenes de gastos de los últimos 5 días
- Validación: Enum de métodos de pago para garantizar consistencia
- Estadísticas: Cálculo automático de totales por categoría y método de pago
📋 Requisitos
- Python >= 3.14
- FastMCP >= 2.13.1
🔧 Instalación
- Clona el repositorio:
git clone https://github.com/BrayanTM/mcp-basico.git
cd mcp-basico
- Instala las dependencias:
pip install fastmcp
🎯 Uso
Ejecutar el Servidor MCP
python main.py
Estructura del CSV
El archivo gastos.csv utiliza la siguiente estructura:
Fecha,Categoría,Cantidad,Método de pago
2025-11-16,Alimentación,45.50,Tarjeta de crédito
Columnas:
- Fecha: Formato ISO 8601 (YYYY-MM-DD)
- Categoría: Texto libre (ej: "Alimentación", "Transporte", "Salud")
- Cantidad: Número decimal con 2 decimales
- Método de pago: Enum validado (Tarjeta de débito, Tarjeta de crédito, Efectivo)
Funcionalidades del MCP
Tool: agregar_gasto
Añade un nuevo gasto al archivo CSV:
agregar_gasto(
fecha="2025-11-16",
categoria="Alimentación",
cantidad=45.50,
metodo_pago=MetodoPago.TARJETA_CREDITO
)
Parámetros:
fecha(str): Fecha en formato YYYY-MM-DDcategoria(str): Categoría del gastocantidad(float): Monto del gastometodo_pago(MetodoPago): Enum con valores válidos
Resource: resource://gastos
Retorna todos los gastos en formato Markdown estructurado, incluyendo:
- Total de gastos registrados
- Suma total gastada
- Agrupación por categoría con subtotales
- Listado detallado de todos los gastos
Prompt: prompt_agregar_gasto
Genera un resumen inteligente de los gastos de los últimos 5 días, agrupados por día y categoría.
📂 Estructura del Proyecto
mcp-basico/
├── main.py # Servidor MCP con tools, resources y prompts
├── gastos.csv # Archivo de datos (generado automáticamente)
├── pyproject.toml # Configuración del proyecto
└── README.md # Documentación
🔐 Métodos de Pago Válidos
El servidor valida los métodos de pago mediante un Enum:
MetodoPago.TARJETA_DEBITO→ "Tarjeta de débito"MetodoPago.TARJETA_CREDITO→ "Tarjeta de crédito"MetodoPago.EFECTIVO→ "Efectivo"
📊 Ejemplo de Salida
Al consultar el resource resource://gastos, obtendrás un formato como:
# Registro de Gastos
Total de gastos registrados: 34
Total gastado: $1,724.54
## Gastos por Categoría
### Alimentación
- Cantidad de gastos: 11
- Total: $525.20
### Transporte
- Cantidad de gastos: 6
- Total: $93.50
...
🛠️ Convenciones de Desarrollo
- Encoding: Siempre usar
utf-8para compatibilidad con caracteres especiales - CSV: Usar
newline=''al abrir archivos en modo escritura - Formato de cantidades: Siempre
.2fpara dos decimales - Manejo de errores: Try/except con mensajes descriptivos en español
- Output para LLMs: Markdown estructurado con jerarquía clara
👤 Autor
BrayanTM
- GitHub: @BrayanTM
Nota: Este servidor MCP está diseñado para ser consumido por agentes de IA que implementen el protocolo MCP, permitiendo gestión automatizada de gastos mediante lenguaje natural.