Money Lover MCP Server

Реализация сервера Model Context Protocol (MCP) на Node.js, который является оберткой для неофициального REST API Money Lover. Сервер предоставляет 27 инструментов MCP, охватывающих аутентификацию, кошельки, категории, транзакции, события, долги и статическую конфигурацию, позволяя ИИ-ассистентам или MCP-совместимым клиентам запрашивать данные о личных финансах и управлять ими.

Возможности

• Автоматическая аутентификация через переменные окружения EMAIL/PASSWORD — для большинства инструментов передача токена не требуется.

• 23 инструмента для чтения, охватывающих информацию о пользователе, кошельки, категории, транзакции, события, долги, иконки, провайдеров и статическую конфигурацию.

• 4 инструмента для записи: создание, обновление и удаление транзакций, кошельков и категорий.

• Большие ответы автоматически обрезаются для поддержания управляемого контекста LLM (настраивается через параметр limit).

• Сервер на базе Stdio, совместимый с Claude Code, Claude Desktop, Cursor и любым хостом MCP.

• Кэширование токенов для каждого email в ~/.moneylover-mcp/ с автоматическим обновлением при ошибках аутентификации.

Related MCP server: YNAB Assistant

Предварительные требования

• Node.js 22 или новее.

• Учетные данные аккаунта Money Lover.

Установка

npm install

Использование

Запустите MCP-сервер через stdio:

npm start

Конфигурация на уровне проекта (Claude Code)

Добавьте .mcp.json в корневой каталог проекта:

{
  "mcpServers": {
    "mcp-moneylover": {
      "command": "node",
      "args": ["/absolute/path/to/moneylover-mcp/src/server.js"],
      "env": {
        "EMAIL": "your@email.com",
        "PASSWORD": "your-password"
      }
    }
  }
}

И включите его в .claude/settings.json:

{ "enabledMcpjsonServers": ["mcp-moneylover"] }

Глобальная конфигурация (Claude Desktop / Cursor)

{
  "mcpServers": {
    "mcp-moneylover": {
      "command": "npx",
      "args": ["@ferdhika31/moneylover-mcp@latest"],
      "env": {
        "EMAIL": "your@email.com",
        "PASSWORD": "your-password"
      }
    }
  }
}

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

Аутентификация

Пользователь

Кошельки

Категории

Транзакции

Статика и конфигурация

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

Примеры промптов, обязательные и опциональные поля, нюансы и распространенные многошаговые шаблоны для каждого инструмента: docs/examples.md.

Использование библиотеки

import { MoneyloverClient } from './src/moneyloverClient.js';

const token = await MoneyloverClient.getToken(email, password);
const client = new MoneyloverClient(token);

const wallets = await client.getWallets();
const txns = await client.getTransactions(walletId, '2026-01-01', '2026-04-30');
await client.addTransaction({ walletId, categoryId, amount: '50000', date: '2026-04-18' });
await client.editTransaction('txn-id', { amount: '60000', note: 'updated' });
await client.deleteTransaction('txn-id');

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

Модульные тесты

Модульные тесты с использованием заглушек — вызовы реального API не требуются:

npm test

Интеграционные тесты (mcp-tester)

mcp-tester — это среда тестирования MCP на основе ReAct-агентов. Она запускает сервер, заставляет LLM вызывать инструменты в ответ на промпты на естественном языке и проверяет, что правильные инструменты были вызваны с правильными аргументами.

Установка

pipx install --index-url https://pypi.artifacts.furycloud.io/simple/ mcp-tester

Конфигурация

tests/mcp-tester/mcps.json — укажите локальный сервер с вашими учетными данными:

{
  "mcp-moneylover": {
    "command": "node",
    "args": ["/absolute/path/to/src/server.js"],
    "transport": "stdio",
    "env": {
      "EMAIL": "your@email.com",
      "PASSWORD": "your-password"
    }
  }
}

Запуск

mcp-tester run-tests \
  --mcps tests/mcp-tester/mcps.json \
  --model gpt-4o-mini \
  --concurrent-runs 3 \
  tests/mcp-tester/read-tools.yaml

Результаты

tests/mcp-tester/read-tools.yaml содержит 25 интеграционных тестов, охватывающих каждый инструмент чтения:

total 25, success 25, failures 0

Ключевые решения, обеспечивающие стабильность тестов:

• Отсутствие параметра токена в инструментах чтения — предоставление опционального поля token приводило к тому, что LLM вставляли в него ID кошельков. Сервер аутентифицируется автоматически через переменные окружения.

• Обрезание ответов — некоторые эндпоинты возвращают сотни тысяч записей из общей базы данных MoneyLover. Инструменты принимают параметр limit (по умолчанию: 20–100), чтобы держать контекст LLM под контролем.

• Обертка в словарь — все ответы инструментов возвращают JSON-объект (никогда не «голый» массив), чтобы проходить валидацию фреймворка MCP.

Тесты инструментов записи (mcp-tester)

Три дополнительных YAML-файла тестируют полный жизненный цикл CRUD для кошельков, категорий и транзакций в три последовательных этапа. Каждый этап запускает все три типа ресурсов одновременно.

Запускайте этапы по порядку — каждый зависит от предыдущего:

# Phase 1: Create
mcp-tester run-tests --mcps tests/mcp-tester/mcps.json --model gpt-4o-mini --concurrent-runs 3 tests/mcp-tester/write-create.yaml

# Phase 2: Edit (after Phase 1 passes)
mcp-tester run-tests --mcps tests/mcp-tester/mcps.json --model gpt-4o-mini --concurrent-runs 3 tests/mcp-tester/write-edit.yaml

# Phase 3: Delete (after Phase 2 passes)
mcp-tester run-tests --mcps tests/mcp-tester/mcps.json --model gpt-4o-mini --concurrent-runs 3 tests/mcp-tester/write-delete.yaml

Результаты по всем трем этапам:

Phase 1 (Create): total 3, success 3, failures 0
Phase 2 (Edit):   total 3, success 3, failures 0
Phase 3 (Delete): total 3, success 3, failures 0

Ключевые проектные решения для тестов инструментов записи:

• Обнаружение перед мутацией — тесты редактирования и удаления инструктируют агента сначала вызвать инструмент чтения (get_wallets, get_categories, get_transactions), чтобы найти цель по имени, а затем вызвать инструмент мутации. Это отражает поведение агента в реальных условиях, когда ID заранее неизвестны.

• args: !any для утверждений инструментов записи — фреймворк требует точного соответствия аргументов. Инструменты записи принимают опциональные поля (icon, with и т.д.), которые агент может включать по своему усмотрению; !any проверяет, что инструмент был вызван и успешно выполнен, не выдавая ошибку из-за безвредных дополнительных полей. Утверждения инструментов чтения могут использовать точное соответствие аргументов, так как их схемы не имеют опциональных полей, которые LLM могла бы добавить спонтанно.

• Предсказуемые идентификаторы — тестовые ресурсы используют фиксированные имена (MCP-Test-Wallet, MCP-Test-Category) и фиксированную заметку (MCP test transaction), чтобы агент мог найти их по имени во время этапов редактирования и удаления без необходимости обмениваться состоянием между запусками тестов.

• Утверждения полной полезной нагрузки при редактировании — edit_transaction — это операция полной замены; тестовый промпт инструктирует агента сначала получить существующую транзакцию (get_transactions) и перенести все текущие значения полей, изменив только заметку. Это подтверждает многошаговое рассуждение, требуемое описанием инструмента.

Заметки по безопасности

• Никогда не коммитьте реальные учетные данные или токены.

• Кэшированные токены хранятся в ~/.moneylover-mcp/ с доступом только для текущего пользователя.

• Удалите эту директорию, чтобы отозвать все кэшированные сессии.