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

Related MCP server: Personal Expense Manager

📋 Requisitos

• Python >= 3.14

• FastMCP >= 2.13.1

🔧 Instalación

1. Clona el repositorio:

git clone https://github.com/BrayanTM/mcp-basico.git
cd mcp-basico

2. 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-DD

• categoria (str): Categoría del gasto

• cantidad (float): Monto del gasto

• metodo_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-8 para compatibilidad con caracteres especiales

• CSV: Usar newline='' al abrir archivos en modo escritura

• Formato de cantidades: Siempre .2f para 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.