ZenMoney MCP

MCP-сервер для личных финансов ZenMoney: 28 инструментов (15 для чтения, 13 для изменения данных), локальный stdio и удалённый Streamable HTTP с OAuth. Финансовая логика находится в scripts/zenmoney/, MCP-адаптер — в zenmoney_mcp/.

Этот репозиторий содержит код, а не размещённый сервер. Для ChatGPT Web и Claude Web разверните собственный HTTPS endpoint и OAuth-провайдер. Один экземпляр рассчитан на одного владельца: он использует один токен ZenMoney и допускает один заданный OAuth subject.

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

Нужны Python 3.10+ и действующий API-токен ZenMoney. Передайте токен процессу через переменную окружения ZENMONEY_TOKEN из своего хранилища секретов. Не вводите его в аргументах командной строки и не сохраняйте в Git.

git clone https://github.com/theblackhaired/zenmoney-mcp.git
cd zenmoney-mcp
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m zenmoney_mcp

На Windows последняя команда — ..venv\Scripts\python.exe -m zenmoney_mcp. Укажите её и защищённую переменную ZENMONEY_TOKEN в настройках stdio MCP-клиента. Есть также точка входа run_stdio.py.

Необязательная ZENMONEY_STATE_DIR задаёт приватный каталог настроек (по умолчанию каталог данных текущего пользователя). Для period=billing_period добавьте туда config.json с параметром billing_period_start_day — целым числом от 1 до 31. Файл может содержать другие личные настройки и не должен попадать в репозиторий. check_auth_status проверяет токен без финансовой записи.

Related MCP server: Finance MCP Server

Инструменты

Полные схемы необязательных аргументов клиент получает через MCP tools/list. Таблицы показывают обязательные аргументы и назначение. Каждый инструмент изменения данных дополнительно требует confirm_write=true; инструменты чтения этого аргумента не требуют.

Чтение — finance:read

Изменения — finance:read и finance:write

Для type=transfer у create_transaction, create_reminder и create_reminder_marker нужен также to_account_id. amount должен быть положительным. В удалённом режиме scope finance:write проверяется сервером отдельно от confirm_write.

Периоды и формат ответа

get_transactions, get_analytics, get_category_report, get_money_flow, get_income_outcome_comparison и get_balance_trend принимают один способ выбора дат:

• period=billing_period, week, month или year; period_offset сдвигает такой период;

• start_date и end_date вместе, обе даты включаются.

Для week обязателен first_weekday от 0 (понедельник) до 6 (воскресенье). Для billing_period нужен billing_period_start_day в приватном config.json. analyze_budget_detailed принимает только billing_period.

Пример аргументов get_analytics:

{"report":"outcome","period":"month","period_offset":0,"response_mode":"full"}

У объёмных инструментов чтения по умолчанию response_mode=compact. Он сокращает ответ для экономии контекста модели. Если данные усечены, ответ содержит _response.truncated=true: это не полный набор данных. Повторите вызов с response_mode=full, чтобы получить все поля и элементы. Ошибки возвращаются полностью.

Особенности расчётов

• Вызов, которому нужны данные ZenMoney, получает свежий полный снимок /v8/diff/. Постоянного кэша операций и счетов нет; снимок остаётся в памяти только на время вызова. После записи сервер повторно проверяет результат в ZenMoney. Открытые ключи JWKS могут кратковременно кэшироваться — это не финансовые данные.

• Переводы исключены из доходов и расходов get_analytics. Валюты по умолчанию разделены; скалярный итог смешанных валют выдаёт ошибку вместо неявного сложения.

• Продвинутые отчёты используют текущие синхронизированные курсы ZenMoney, а не исторический курс на дату операции.

• get_balance_trend восстанавливает прошлые остатки из текущих остатков и истории операций; готовых ежедневных снимков ZenMoney здесь нет.

• Режим «Планов» и настройки переводов берутся из синхронизированного пользователя, кроме явных локальных переопределений. В режиме balance_vs_expense расчёт разниц использует difference_calculation_mode=NONE.

• Фильтры аналитики по счёту, категории и получателю объединяются через AND. Неоднозначное короткое название категории бюджета вызывает ошибку; можно указать ID или полный путь.

• report=turnover в get_analytics возвращает UNSUPPORTED_CALCULATION. В сравнении доходов и расходов AVERAGE_VALUES для периода до 31 дня фактически использует WHOLE_PERIOD, для более длинного периода возвращает UNSUPPORTED_CALCULATION.

Удалённый сервер и OAuth

Пример публичного endpoint: https://mcp.example.com/mcp. Приложение слушает 127.0.0.1:8769; HTTPS обеспечивает reverse proxy. В deploy/ есть обезличенные примеры nginx, systemd и необязательного Keycloak с PostgreSQL. Замените example.com, пользователя службы и пути. Compose не создаёт realm, пользователя, scopes, audience или политику регистрации OAuth-клиентов.

.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m uvicorn zenmoney_mcp.remote:create_app --factory --host 127.0.0.1 --port 8769

Без четырёх OAuth-переменных удалённый сервер не запустится. Токен ZenMoney и OAuth-токены клиентов — разные учётные данные; клиентам передаются только их OAuth-токены.

Порядок развёртывания на Linux:

1. Подготовьте DNS и сертификаты для MCP и OAuth-провайдера. Оставьте Uvicorn и Keycloak на loopback; используйте deploy/nginx.https.conf и deploy/nginx.auth.https.conf как шаблоны входящих HTTPS-маршрутов.

2. Установите зависимости в venv, создайте отдельного системного пользователя и приватный каталог состояния. Скопируйте deploy/server.env.template вне checkout (например, в /etc/zenmoney-mcp/server.env), задайте ZENMONEY_TOKEN и все OAuth-переменные, ограничьте чтение файла владельцем службы. Пример unit — deploy/zenmoney-mcp.service; после подстановки путей проверьте его через systemd-analyze verify.

3. Поднимите и настройте OAuth-провайдер. Для отдельного Keycloak можно использовать deploy/compose.yaml и предварительно создать приватный env-файл скриптом deploy/generate_env.py. Затем вручную настройте realm, пользователя, scopes, audience и регистрацию клиентов; compose выполняет только запуск служб.

4. После проверки issuer, JWKS и токена запустите MCP-службу, проверьте metadata и ответ 401 без токена. Только затем подключайте веб-клиенты.

5. Если нужен таймер Claude DCR, установите deploy/zenmoney-mcp-claude-scopes.service и .timer как user units. Предоставьте этой службе отдельный приватный Keycloak admin env-файл, доступный её пользователю, и проверьте результат первого запуска. Не храните admin-реквизиты в checkout.

Провайдер должен поддерживать Authorization Code + PKCE S256 и discovery. Сервер проверяет подпись RS256/ES256, iss, exp, sub, scope и одиночное строковое aud, точно равное ZENMONEY_MCP_RESOURCE, в каждом запросе. Разрешите клиентам оба scope — finance:read и finance:write: сервер объявляет их при первоначальном OAuth-запросе, поэтому запрет finance:write в DCR может сорвать подключение ещё до вызова записи. При наличии RFC 8707 настройте resource indicator; иначе настройте audience mapper и проверьте итоговое aud. См. руководство Keycloak по MCP.

Для ChatGPT с Keycloak используйте DCR или заранее зарегистрированного клиента: текущая документация Keycloak указывает несовместимость его экспериментального CIMD с документом ChatGPT. Ограничьте redirect URI и Trusted Hosts фактическими клиентами. Для Claude deploy/reconcile_claude_dcr_scopes.py поддерживает необязательный finance:write у строго распознанных DCR-клиентов в уже настроенном realm master; пример таймера есть в deploy/. Скрипт не создаёт пользователя и не выдаёт согласие.

Безопасная проверка маршрута:

curl -i https://mcp.example.com/.well-known/oauth-protected-resource/mcp
curl -i https://mcp.example.com/mcp
curl -i https://auth.example.com/auth/realms/master/.well-known/openid-configuration

Ожидаются соответственно 200 с resource и authorization_servers, 401 с WWW-Authenticate и discovery провайдера. Ответ 401 без токена подтверждает защиту маршрута, но не права пользователя.

ChatGPT Web

1. В ChatGPT откройте Settings → Security and login и включите Developer mode, если он доступен аккаунту.

2. В ChatGPT Plugins добавьте полный HTTPS URL с /mcp и проверьте обнаруженные инструменты.

3. Начните новый чат, выберите подключение и пройдите OAuth-вход.

4. Если Keycloak требует redirect URI, скопируйте точное значение из страницы подключения ChatGPT: оно зависит от поддержки issuer identification. Не используйте угаданный wildcard.

Инструкция OpenAI по подключению · Требования OpenAI к OAuth

Claude Web

1. Откройте Customize → Connectors → Add custom connector и укажите тот же URL с /mcp.

2. Выберите OAuth. С Keycloak доступны Register automatically (DCR) или заранее созданный OAuth client; CIMD используйте только после проверки совместимости вашей версии Keycloak.

3. Для hosted Claude зарегистрируйте callback https://claude.ai/api/mcp/auth_callback. После входа проверьте чтение; если нужен scope записи у DCR-клиента, выполните reconciler и проверьте его результат.

Инструкция Claude по коннекторам · OAuth-требования Claude

Проверка и структура

.venv/bin/python -m pip install -r requirements-dev.txt
.venv/bin/python -m pytest -q

Тесты используют синтетические данные; реальные токены и выгрузки не нужны.

Никогда не добавляйте в Git config.json, .cache.json, .env, токены, реальные суммы, имена счетов и финансовые выгрузки. Перед подключением модели проверьте, какие инструменты записи и scope она получит.

Лицензия

MIT — см. LICENSE.