MCP-сервер Lunch Money

TypeScript Node.js Лицензия

Сервер Model Context Protocol (MCP), который позволяет ИИ-агентам взаимодействовать с вашими личными финансовыми данными в Lunch Money.

Возможности

Этот MCP-сервер предоставляет 15 инструментов для управления вашими финансовыми данными:

Пользователь и аккаунт

• get_user — Получение информации о вашем профиле и аккаунте

Категории

• get_categories — Список всех категорий (плоский или вложенный)

• create_category — Создание новых пользовательских категорий

• update_category — Изменение существующих категорий

Транзакции

• get_transactions — Поиск транзакций с фильтрами (диапазон дат, категория, статус и т. д.)

• create_transaction — Добавление новых транзакций (по одной или пакетами до 500)

• update_transaction — Обновление транзакций или их разделение на несколько записей

Активы и счета

• get_assets — Список активов, управляемых вручную

• create_asset — Добавление новых активов, управляемых вручную

• get_plaid_accounts — Список банковских счетов, подключенных через Plaid

• trigger_plaid_fetch — Запуск синхронизации счетов Plaid

Бюджеты и планирование

• get_budgets — Просмотр бюджетов и расходов за любой диапазон дат

• upsert_budget — Установка или обновление сумм бюджета

• get_recurring_items — Просмотр повторяющихся расходов и доходов

Теги

• get_tags — Список всех тегов транзакций

Related MCP server: LunchMoney MCP Server

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

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

• Аккаунт Lunch Money с доступом к API

• API-ключ Lunch Money с страницы разработчиков

Установка

Вариант 1: Клонирование и сборка (локальный транспорт stdio)

Для локального использования с Cursor, Claude Desktop или другими MCP-клиентами на базе stdio:

# Clone the repository
git clone https://github.com/yourusername/lunchmoney-mcp.git
cd lunchmoney-mcp

# Install dependencies
npm install

# Build the TypeScript
npm run build

Вариант 2: Cloudflare Workers (удаленный транспорт HTTP)

Развертывание в качестве удаленного MCP-сервера, доступного через HTTP:

# Clone the repository
git clone https://github.com/yourusername/lunchmoney-mcp.git
cd lunchmoney-mcp

# Install dependencies
npm install

# Set your API key as a secret
npx wrangler secret put LUNCH_MONEY_API_KEY
# Enter your Lunch Money API key when prompted

# Deploy to Cloudflare Workers
npm run deploy

Вариант 3: Использование с npx (только локально)

Вы можете запустить MCP-сервер напрямую без клонирования:

npx -y lunchmoney-mcp

Примечание: Вам все равно потребуется установить переменную окружения LUNCH_MONEY_API_KEY.

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

Получение API-ключа

1. Войдите в Lunch Money

2. Перейдите в Settings → Developers

3. Создайте новый API-ключ

4. Скопируйте ключ (храните его в безопасности!)

Cursor IDE

Добавьте в конфигурацию MCP Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "lunchmoney": {
      "command": "node",
      "args": ["/path/to/lunchmoney-mcp/dist/index.js"],
      "env": {
        "LUNCH_MONEY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Или через npx:

{
  "mcpServers": {
    "lunchmoney": {
      "command": "npx",
      "args": ["-y", "lunchmoney-mcp"],
      "env": {
        "LUNCH_MONEY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Desktop

Добавьте в конфигурацию Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json на macOS):

{
  "mcpServers": {
    "lunchmoney": {
      "command": "node",
      "args": ["/path/to/lunchmoney-mcp/dist/index.js"],
      "env": {
        "LUNCH_MONEY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Другие MCP-клиенты

Любой MCP-клиент, поддерживающий транспорт stdio, может использовать этот сервер. Установите переменную окружения LUNCH_MONEY_API_KEY и запустите:

node /path/to/lunchmoney-mcp/dist/index.js

Удаленный MCP через Cloudflare Workers (свой API-ключ)

Развертывание Cloudflare Workers спроектировано как публичный MCP-сервер, где каждый пользователь использует свой собственный API-ключ. Сервер никогда не хранит API-ключи.

Как это работает:

1. Разверните сервер на Cloudflare Workers (или используйте общий экземпляр)

2. Каждый пользователь подключается со своим API-ключом Lunch Money

3. API-ключ отправляется с каждым запросом в заголовке X-LunchMoney-API-Key

Подключение через прокси mcp-remote:

{
  "mcpServers": {
    "lunchmoney": {
      "command": "npx",
      "args": ["mcp-remote", "https://lunchmoney-mcp.your-subdomain.workers.dev/mcp"],
      "env": {
        "MCP_HEADERS": "X-LunchMoney-API-Key: your_api_key_here"
      }
    }
  }
}

Примечание: Прокси mcp-remote должен поддерживать пользовательские заголовки. Некоторые MCP-клиенты могут пока не поддерживать эту функцию.

⚠️ Относитесь к файлу mcp.json как к файлу с учетными данными. Теперь он содержит ваш API-ключ Lunch Money. Никогда не добавляйте его в репозиторий Git (включая репозитории с dotfiles). Добавьте его в .gitignore, если он находится внутри одного из них. Любой, у кого есть доступ на чтение к этому файлу, может читать и изменять ваши данные Lunch Money.

Безопасность: Это наиболее безопасная модель, потому что:

• Сервер никогда не хранит API-ключи

• Каждый пользователь получает доступ только к своим данным

• API-ключи передаются с каждым запросом, а не хранятся на сервере

• Публичный воркер обеспечивает ограничение частоты запросов (rate limiting) по IP и никогда не логирует тела запросов или заголовки

Развертывание на Cloudflare Workers (публичный сервер)

Это создает публичный MCP-сервер, который может использовать любой желающий со своим API-ключом. Сервер не хранит учетные данные.

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

• Аккаунт Cloudflare (подходит бесплатный тариф)

• Установленный Wrangler CLI

Развертывание

1. Установите зависимости:

 npm install

2. Разверните на Cloudflare Workers:

 npm run deploy

3. Ваш публичный MCP-сервер запущен! URL будет показан в выводе:

 https://lunchmoney-mcp.your-account.workers.dev/mcp

Опционально: Вы можете установить API-ключ по умолчанию для тестирования:

npx wrangler secret put LUNCH_MONEY_API_KEY

Как подключаются пользователи

Пользователи подключаются к вашему публичному серверу со своим API-ключом Lunch Money:

{
  "mcpServers": {
    "lunchmoney": {
      "command": "npx",
      "args": ["mcp-remote", "https://lunchmoney-mcp.your-account.workers.dev/mcp"],
      "env": {
        "MCP_HEADERS": "X-LunchMoney-API-Key: their_api_key_here"
      }
    }
  }
}

Локальная разработка с Wrangler

# Run locally with hot reload
npm run dev:worker

Модель безопасности

• Сервер никогда не хранит API-ключи — ключи передаются с каждым запросом через заголовок

• Пользователи получают доступ только к своим данным — каждый запрос использует ключ пользователя

• Публичный доступ — любой может использовать сервер, но им нужен собственный аккаунт Lunch Money

Это похоже на работу публичных API-шлюзов — инфраструктура общая, но учетные данные у каждого пользователя свои.

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

После настройки вы можете задавать своему ИИ-ассистенту вопросы, например:

• "Покажи мои расходы по категориям за этот месяц"

• "Какая была моя самая крупная трата на прошлой неделе?"

• "Распредели по категориям все мои нераспределенные транзакции за март"

• "Создай новую категорию под названием 'Freelance Income'"

• "Сколько я потратил на продукты в первом квартале?"

• "Перечисли все мои повторяющиеся подписки"

Разработка

Локальный режим stdio (для Cursor, Claude Desktop)

# Install dependencies
npm install

# Run in development mode with hot reload
npm run dev

# Build for production
npm run build

# Type check without emitting
npm run typecheck

# Test with MCP Inspector
npm run inspect

Режим Cloudflare Workers (для удаленного доступа по HTTP)

# Build the Worker
npm run build

# Run locally with Wrangler
npm run dev:worker

# Deploy to production
npm run deploy

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

src/
├── index.ts           # MCP server entry point (stdio mode)
├── worker.ts          # Cloudflare Workers entry point (HTTP mode)
├── client.ts          # Lunch Money API client
├── types.ts           # TypeScript type definitions
├── tool-utils.ts      # Shared tool utilities
└── tools/             # Individual tool implementations
    ├── user.ts
    ├── categories.ts
    ├── transactions.ts
    ├── assets.ts
    ├── plaid.ts
    ├── budgets.ts
    ├── recurring.ts
    └── tags.ts

Режимы развертывания

Оба режима используют одни и те же реализации инструментов и API-клиент.

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

Защита API-ключа

• Никогда не коммитьте свой API-ключ. Файл .env по этой причине находится в .gitignore.

• Храните ключ в переменных окружения или безопасных файлах конфигурации MCP.

• Если ваш ключ был скомпрометирован, немедленно аннулируйте его на странице Lunch Money Developers и создайте новый.

Конфиденциальность данных

• Этот сервер выступает в качестве прокси между вашим ИИ-ассистентом и Lunch Money.

• Ваши финансовые данные обрабатываются в соответствии с политикой конфиденциальности Lunch Money.

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

Разрешения

Предоставленный вами API-ключ определяет, какие действия может выполнять MCP-сервер. API-ключи Lunch Money могут:

• Читать все ваши финансовые данные

• Создавать, обновлять и удалять транзакции

• Изменять категории и бюджеты

• Запускать синхронизацию Plaid

Справочник API

Этот MCP-сервер использует Lunch Money API v1.

Ограничения частоты запросов (Rate Limits)

API Lunch Money имеет ограничения по частоте запросов. MCP-сервер будет передавать любые ошибки ограничения частоты от API. Если вы столкнулись с ограничением, подождите несколько минут перед повторной попыткой.

Обработка ошибок

Сервер обрабатывает ошибки API Lunch Money и возвращает их как ошибки инструментов MCP. Некоторые примечания:

• Lunch Money иногда возвращает логические ошибки как ответы HTTP 200 — они нормализуются в корректные ошибки

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

• Полные сведения об ошибках записываются в stderr для отладки

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

Ошибка "Missing LUNCH_MONEY_API_KEY"

Переменная окружения LUNCH_MONEY_API_KEY не установлена. Проверьте конфигурацию MCP и убедитесь, что ключ настроен правильно.

Ошибка "Unauthorized"

Ваш API-ключ может быть недействительным или аннулированным. Проверьте свой ключ на странице https://my.lunchmoney.app/developers

Транзакции не появляются

Если вы используете счета, подключенные через Plaid, вам может потребоваться запустить синхронизацию:

• Используйте инструмент trigger_plaid_fetch для постановки фоновой синхронизации в очередь

• Обратите внимание, что это только ставит задачу в очередь — транзакции могут появиться через несколько минут

Участие в разработке

Вклад приветствуется! Пожалуйста, не стесняйтесь отправлять Pull Request.

1. Сделайте форк репозитория

2. Создайте ветку для вашей функции (git checkout -b feature/amazing-feature)

3. Закоммитьте изменения (git commit -m 'feat: add amazing feature')

4. Отправьте изменения в ветку (git push origin feature/amazing-feature)

5. Откройте Pull Request

Лицензия

Этот проект лицензирован по лицензии ISC — подробности см. в файле LICENSE.

Благодарности

• Создано с использованием Model Context Protocol SDK

• Работает на базе Lunch Money

Поддержка

• По вопросам, связанным с этим MCP-сервером, пожалуйста, откройте issue на GitHub

• По вопросам API Lunch Money см. документацию API Lunch Money

• По вопросам протокола MCP см. документацию MCP

Отказ от ответственности: Это неофициальный общественный проект. Он не связан с Lunch Money и не поддерживается ими.