Personal Expense Tracker MCP

Qué hace este proyecto

Personal Expense Tracker MCP es un servidor MCP local y sencillo para registrar gastos personales

Almacena los datos de gastos en un archivo CSV local

El servidor ofrece a un cliente MCP cinco herramientas específicas

• añadir un nuevo gasto

• listar los gastos guardados

• crear un resumen de gastos

• actualizar un gasto existente

• eliminar un gasto existente

El proyecto está diseñado para ser simple y fácil de ejecutar localmente

No se necesita ninguna cuenta bancaria ni API externa

Related MCP server: expense-mcp

Requisitos

Antes de empezar, asegúrate de tener instalado lo siguiente

• Node.js versión 20 o superior

• npm

• Git

Comprueba Node.js

node --version

Comprueba npm

npm --version

Comprueba Git

git --version

Instalación

1 Clona el repositorio

git clone https://github.com/MohammadYousef-001/Personal-Expenses-Tracker.git

2 Entra en la carpeta del proyecto

cd Personal-Expenses-Tracker

3 Instala los paquetes

npm install

Espera a que npm termine de instalar los paquetes necesarios

Archivo de datos

Los gastos se guardan localmente en

data/expenses.csv

El archivo CSV utiliza estas columnas

id,amount,category,date,description

No cambies los nombres de las columnas

Ejecutar el servidor MCP

Para iniciar el servidor, ejecuta

npm run dev

El servidor utiliza la entrada y la salida estándar para la comunicación MCP

Es un servidor local y no necesita un puerto web

Ejecutar MCP Inspector

MCP Inspector es la forma más sencilla de probar las herramientas manualmente

Ejecuta

npm run inspect

Se debería abrir una ventana del navegador con MCP Inspector

Si no se abre automáticamente, usa la URL que se muestra en el terminal

En el Inspector

1. Conecta con el servidor

2. Abre la sección Tools

3. Elige una herramienta

4. Introduce la entrada

5. Haz clic en Execute Tool

6. Comprueba el resultado

Herramientas disponibles

Herramienta 1 add_expense

Usa add_expense para guardar un nuevo gasto

Entradas

amount

La cantidad de dinero gastada

Debe ser un número positivo

category

La categoría del gasto

Ejemplos

groceries
transport
bills
shopping

La categoría se guarda en minúsculas para que los nombres de las categorías sean coherentes

date

La fecha del gasto

Debe usar

YYYY-MM-DD

Ejemplo

2026-08-12

La fecha también debe ser una fecha real del calendario

Esto no es válido

2026-99-99

description

Información breve y opcional sobre el gasto

Ejemplo

{
  "amount": 25,
  "category": "groceries",
  "date": "2026-08-12",
  "description": "milk and bread"
}

Una solicitud correcta añade el gasto a

data/expenses.csv

Herramienta 2 list_expenses

Usa list_expenses para ver los gastos guardados

Sin filtros

{}

Filtrar por categoría

{
  "category": "groceries"
}

Filtrar por mes

{
  "month": "2026-08"
}

Usar ambos filtros

{
  "month": "2026-08",
  "category": "groceries"
}

El mes debe usar

YYYY-MM

El mes debe estar entre 01 y 12

Esto no es válido

2026-99

Herramienta 3 get_spending_summary

Usa get_spending_summary para ver un resumen de tus gastos

Ejemplo

{
  "month": "2026-08"
}

El resultado puede incluir

• el mes seleccionado

• el importe total gastado

• el número de gastos

• el gasto total de cada categoría

Resultado de ejemplo

month: 2026-08
total amount: 150
expense count: 4

category totals:
groceries: 80
transport: 30
bills: 40

Los valores reales dependen de los datos que hay dentro de data/expenses.csv

Prompts de ejemplo

Añadir un gasto

I spent 25 on groceries today

Esto puede usar

add_expense

Buscar gastos

show my grocery expenses for this month

Esto puede usar

list_expenses

Consultar gastos

how much did I spend this month

Esto puede usar

get_spending_summary

Validación de entrada

El proyecto comprueba la entrada de las herramientas antes de usarla

Ejemplos de entradas no válidas

• importe negativo

• importe cero

• formato de fecha incorrecto

• fecha de calendario imposible

• mes no válido

• categoría demasiado larga

• descripción demasiado larga

La entrada no válida se rechaza antes de guardarla

Probar los esquemas

Ejecuta

npm run check:schema

Un resultado correcto debería mostrar

All expense schemas are valid.

Solución de problemas

Problema 1: faltan paquetes

Si ves un error que indica que no se puede encontrar un paquete o módulo, ejecuta

npm install

Después inténtalo de nuevo

npm run dev

Problema 2: MCP Inspector no se inicia

Asegúrate de que los paquetes estén instalados

npm install

Después ejecuta

npm run inspect

Si sigue ejecutándose desde una sesión anterior, pulsa

Ctrl + C

Después vuelve a iniciar el Inspector

Problema 3: error de TypeScript o de esquema

Ejecuta

npm run check:schema

Si todo es correcto, deberías ver

All expense schemas are valid.

Si hay un error, comprueba el nombre del archivo y el número de línea que se muestran en el terminal

Corrige el error antes de volver a iniciar el Inspector

Problema 4: fecha no válida

Una fecha válida debe usar

YYYY-MM-DD

Ejemplo válido

2026-08-12

Ejemplo no válido

2026-99-99

Problema 5: no se devuelven gastos

Comprueba

data/expenses.csv

Asegúrate de que el archivo contenga filas de gastos por debajo de la cabecera del CSV

Si el archivo solo contiene la cabecera, es normal que el resultado esté vacío

Estructura del proyecto

Archivos importantes del proyecto

Personal-Expenses-Tracker/
│
├── data/
│   └── expenses.csv
│
├── docs/
│   ├── design.md
│   └── threat-model.md
│
├── examples/
│
├── src/
│   ├── index.ts
│   ├── schemas/
│   ├── tools/
│   └── lib/
│
├── SECURITY.md
├── package.json
└── README.md

Seguridad

La entrada de las herramientas se trata como una entrada no fiable

El proyecto valida la entrada antes de las operaciones importantes

La ruta del archivo de gastos está controlada por la aplicación

Los errores devueltos al cliente MCP se mantienen breves

Los errores más detallados se quedan en el terminal local para depurar

Las herramientas de gastos no requieren solicitudes de red externas

Hay más información de seguridad en

SECURITY.md

Alcance del proyecto

Este proyecto es una pequeña herramienta local de seguimiento de gastos personales

No incluye

• conexiones con cuentas bancarias

• importaciones bancarias automáticas

• inicio de sesión de usuario

• base de datos en la nube

• aplicación gráfica completa

• previsión financiera

El objetivo principal es proporcionar herramientas MCP sencillas para el seguimiento local de gastos

Licencia

Este proyecto usa la licencia MIT

Consulta LICENSE