Personal Expense Tracker MCP

Что этот проект делает

Personal Expense Tracker MCP — это простой локальный MCP-сервер для учёта личных расходов

Он хранит данные о расходах в локальном CSV-файле

Сервер предоставляет MCP-клиенту пять инструментов

• добавить новый расход

• вывести список сохранённых расходов

• создать сводку по расходам

• обновить существующий расход

• удалить существующий расход

Проект создан простым и лёгким для локального запуска

Ни банковский счёт, ни внешний API не нужны

Related MCP server: expense-mcp

Требования

Перед началом убедитесь, что у вас установлено

• Node.js версии 20 или нове

• npm

• Git

Проверьте Node.js

node --version

Проверьте npm

npm --version

Проверьте Git

git --version

Установка

1 Клонируйте репозиторий

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

2 Перейдите в папку проекта

cd Personal-Expenses-Tracker

3 Установите пакеты

npm install

Дождитесь, пока npm завершит установку необходимых пакетов

Файл данных

Расходы хранятся локально в

data/expenses.csv

В CSV-файле используются такие столбцы

id,amount,category,date,description

Не меняйте названия столбцов

Запуск MCP-сервера

Чтобы запустить сервер, выполните

npm run dev

Сервер использует стандартный ввод и вывод для MCP-взаимодействия

Это локальный сервер, и ему не нужен веб-порт

Запуск MCP Inspector

MCP Inspector — это самый простой способ проверить инструменты вручную

Выполните

npm run inspect

В браузере должно открыться окно с MCP Inspector

Если оно не открылось автоматически, используйте URL, указанный в терминале

В Inspector

1. подключитесь к серверу

2. откройте раздел Tools

3. выберите инструмент

4. введите входные данные

5. нажмите Execute Tool

6. проверьте результат

Доступные инструменты

Инструмент 1: add_expense

Используйте add_expense, чтобы сохранить новый расход

Входные данные

amount

Сумма потраченных денег

Она должна быть положительным числом

category

Категория расхода

Примеры

groceries
transport
bills
shopping

Категория хранится в нижнем регистре, поэтому названия категорий остаются единообразными

date

Дата расхода

Она должна использовать

YYYY-MM-DD

Пример

2026-08-12

Дата также должна быть реальной календарной датой

Это недопустимо

2026-99-99

description

Необязательная краткая информация о расходе

Пример

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

Успешный запрос добавляет расход в

data/expenses.csv

Инструмент 2: list_expenses

Используйте list_expenses, чтобы просмотреть сохранённые расходы

Без фильтров

{}

Фильтр по категории

{
  "category": "groceries"
}

Фильтр по месяцу

{
  "month": "2026-08"
}

Используйте оба фильтра

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

Месяц должен использовать

YYYY-MM

Месяц должен быть между 01 и 12

Это недопустимо

2026-99

Инструмент 3: get_spending_summary

Используйте get_spending_summary, чтобы увидеть сводку по расходам

Пример

{
  "month": "2026-08"
}

Результат может включать

• выбранный месяц

• общую сумму расходов

• количество расходов

• общую сумму расходов по каждой категории

Пример результата

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

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

Реальные значения зависят от данных в data/expenses.csv

Примерные запросы

Добавление расхода

I spent 25 on groceries today

Для этого можно использовать

add_expense

Поиск расходов

show my grocery expenses for this month

Для этого можно использовать

list_expenses

Проверка расходов

how much did I spend this month

Для этого можно использовать

get_spending_summary

Валидация входных данных

Проект проверяет входные данные инструмента перед его использованием

Примеры недопустимых данных

• отрицательная сумма

• нулевая сумма

• ошибочный формат даты

• невозможная календарная дата

• недопустимый месяц

• слишком длинная категория

• слишком длинное описание

Недопустимые данные отклоняются до сохранения

Тестирование схем

Выполните

npm run check:schema

При успешном выполнении должно появиться

All expense schemas are valid.

Устранение неполадок

Проблема 1: отсутствуют пакеты

Если вы видите ошибку о том, что пакет или модуль не найден, выполните

npm install

Затем попробуйте снова

npm run dev

Проблема 2: MCP Inspector не запускается

Убедитесь, что пакеты установлены

npm install

Затем выполните

npm run inspect

Если старый процесс Inspector всё ещё работает, нажмите

Ctrl + C

Затем снова запустите Inspector

Проблема 3: ошибка TypeScript или схемы

Выполните

npm run check:schema

Если всё правильно, вы должны увидеть

All expense schemas are valid.

Если есть ошибка, проверьте имя файла и номер строки, указанных в терминале

Исправьте ошибку перед повторным запуском Inspector

Проблема 4: недопустимая дата

Допустимая дата должна использовать

YYYY-MM-DD

Допустимый пример

2026-08-12

Недопустимый пример

2026-99-99

Проблема 5: расходы не возвращаются

Проверьте

data/expenses.csv

Убедитесь, что в файле есть строки с расходами под заголовком CSV

Если файл содержит только заголовок, пустой результат — это нормально

Структура проекта

Важные файлы проекта

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

Безопасность

Входные данные инструментов считаются недоверенными

Проект проверяет входные данные перед важными операциями

Путь к файлу с расходами контролируется приложением

Ошибки, возвращаемые MCP-клиенту, остаются краткими

Более подробные ошибки остаются в локальном терминале для отладки

Инструменты для работы с расходами не требуют внешних сетевых запросов

Дополнительные сведения о безопасности доступны в

SECURITY.md

Область проекта

Этот проект — небольшой локальный учётный журнал личных расходов

Он не включает

• подключения к банковским счетам

• автоматический импорт из банка

• вход пользователя

• облачную базу данных

• полноценное графическое приложение

• финансовое прогнозирование

Основная цель — предоставить простые MCP-инструменты для локального ведения учёта расходов

License

Этот проект использует лицензию MIT

См. LICENSE