YNAB MCP Server

Удалённый MCP-сервер (Streamable HTTP) для анализа бюджета в YNAB. Готов к деплою на Railway.

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

• Один запрос на синхронизацию. У YNAB лимит 200 запросов/час, поэтому весь план (бюджет) загружается одним GET /plans/{id}, а дальше обновляется delta-запросами (last_knowledge_of_server). Кэш живёт в памяти; данные считаются свежими CACHE_TTL_SECONDS (по умолчанию 5 минут).

• Суммы — в валюте плана, а не в milliunits (12.5 = 12,50). Отрицательные — расходы.

• Сплиты раскрываются в отдельные строки, поэтому отчёты по категориям считаются корректно.

• Счета, категории и получатели принимаются по id или по (частичному) имени.

• Только чтение по умолчанию. Инструменты записи включаются переменной YNAB_ALLOW_WRITES=true.

Related MCP server: YNAB MCP Server

Инструменты

С YNAB_ALLOW_WRITES=true дополнительно: create_transaction, update_transactions (категоризация/подтверждение пачкой), delete_transaction, set_category_assigned.

Переменные окружения

Деплой на Railway

1. Railway → New Project → Deploy from GitHub repo → выбрать этот репозиторий. Сборка и запуск описаны в railway.json (npm ci --include=dev && npm run build, npm start, healthcheck /health).

2. Variables: задать YNAB_ACCESS_TOKEN и MCP_AUTH_TOKEN (и при желании остальные).

3. Settings → Networking → Generate Domain — получить публичный адрес вида https://ynab-mcp-production.up.railway.app.

4. Проверить: curl https://<домен>/health → {"status":"ok",...}.

Подключение к Claude

Claude.ai / Claude Desktop (Settings → Connectors → Add custom connector): указать URL с токеном в пути:

https://<домен>/mcp/<MCP_AUTH_TOKEN>

Claude Code:

claude mcp add --transport http ynab https://<домен>/mcp --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

Сервер принимает токен либо в заголовке Authorization: Bearer …, либо сегментом пути /mcp/<token>. URL с токеном — это пароль к вашим финансам, не публикуйте его.

Локальный запуск

npm install
npm run build
YNAB_ACCESS_TOKEN=... MCP_AUTH_TOKEN=dev npm start        # HTTP на :3000
YNAB_ACCESS_TOKEN=... npm run start:stdio                 # stdio-режим для локальных клиентов
npm test                                                  # e2e-тест на моке YNAB API

Примеры вопросов

• «Сделай обзор бюджета за этот месяц: где перерасход и что недофинансировано?»

• «На что я тратил больше всего за последние 3 месяца? Сравни с предыдущими тремя.»

• «Покажи динамику расходов на рестораны за год.»

• «Какая у меня норма сбережений по месяцам?»

• «Сколько в месяц уходит на подписки и регулярные платежи?»