monarch-mcp2-obot

Однотенантный MCP-сервер Monarch Money для самостоятельного размещения за obot, форкнут из erikrubstein/monarch-mcp2 (сам по себе не форк более распространённого семейства robcerda/monarch-mcp-server — это независимая реализация на основе собственного API-клиента monarch-api2).

Этот форк существует по трём причинам, не охваченным апстримом:

1. Перенесён на MCP Python SDK v2 (MCPServer, а не устаревший v1 FastMCP).

2. Процедура входа, созданная для obot: учётные данные настраиваются один раз как переменные окружения, с опциональной поддержкой TOTP-сида, позволяющей автоматически проходить MFA-вызов приложения-аутентификатора — без браузера, без системной связки ключей, без ручного копирования шестизначного кода.

3. Намеренно однотенантный: ровно один аккаунт Monarch на каждый запущенный экземпляр. Ни один вызов инструмента не может быть направлен на сессию другого аккаунта, даже если клиент попытается отправить такой, — см. «Однотенантный, намеренно» ниже.

Не аффилирован с Monarch Money, не одобрен и не поддерживается Monarch Money.

Что унаследовано от апстрима

125 инструментов в 14 группах — accounts, transactions, budget, cashflow, categories, goals, household, investments, merchants, receipts, recurring, reports, tags — без изменений относительно monarch-mcp2. Смотрите его список инструментов и заметки о дизайне, чтобы узнать, что охвачено, а что намеренно выходит за рамки (правила транзакций и автоматизация, процедуры подключения счетов у провайдеров, граничные случаи администрирования аккаунтов).

Related MCP server: monarch-mcp

Что здесь отличается

Аутентификация: auth_login, auth_status

Два новых инструмента поверх auth_create_session / auth_save_session / auth_load_session из апстрима (которые по-прежнему работают для полностью ручного разового входа):

• auth_login — аргументы не нужны, если в окружении сервера настроены MONARCH_EMAIL / MONARCH_PASSWORD (а для MFA через приложение-аутентификатор — MONARCH_TOTP_SECRET). Автоматически обрабатывает MFA-вызов, вычисляя текущий код из сида. Передайте email / password / totp_secret / mfa_code явно, чтобы переопределить их для разового входа, не трогая конфигурацию сервера.

• auth_status — сообщает, существует ли сессия и действительна ли она на данный момент (по умолчанию один лёгкий API-вызов), никогда не возвращая токен сессии.

Сервер также пытается выполнить этот вход автоматически при запуске, если настроены учётные данные, — по принципу best-effort, без фатальных последствий, так что неверный пароль или недоступная сеть не помешают серверу запуститься; auth_status и auth_login остаются доступными для диагностики и повторной попытки.

TOTP-сид: тот же base32-секрет, с которым было бы зарегистрировано приложение-аутентификатор (то, что вы сканировали бы как QR-код). Monarch показывает его один раз, когда вы включаете MFA через приложение-аутентификатор, — сохраните его сразу, иначе вам придётся отключить и снова включить MFA, чтобы получить новый. Это применимо только в том случае, если метод MFA вашего аккаунта — приложение-аутентификатор; MFA по коду из электронной почты так автоматизировать нельзя (нет сида, из которого можно вычислить код), и для передачи свежего кода через аргумент mfa_code в auth_login по-прежнему нужен человек.

Однотенантный, намеренно

session_path присутствует в каждой нижележащей функции (соглашение monarch-api2), но удаляется из публичной схемы каждого инструмента до того, как она будет предоставлена MCP-клиенту, — см. tool_metadata.py. Одно развёртывание, один аккаунт Monarch, один файл сессии, выбранный один раз через MONARCH_SESSION_PATH / MONARCH_CONFIG_DIR. Это не просто умолчание в конфигурации: ни один вызов инструмента не может переопределить его в рамках запроса — так задумано, даже если клиент всё равно передаст его (см. tests/test_server.py::test_tool_call_ignores_session_path_even_if_a_client_sends_it).

Выбор транспорта для двух моделей развёртывания obot

obot поддерживает MCP-серверы двумя способами, важными здесь: на основе команды/uvx (stdio) и на основе Docker (порт плюс конечная точка streamable-http). Оба поддерживаются через MCP_TRANSPORT (по умолчанию stdio); Docker-образ по умолчанию устанавливает его в streamable-http. См. config.py / server.py.

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

Относитесь к MONARCH_PASSWORD и MONARCH_TOTP_SECRET как к любым другим секретам — однопользовательская модель MCP-сервера obot помечает такие поля как «конфиденциальные», когда администратор настраивает сервер; воспользуйтесь этим.

Запуск

obot, на основе команды/uvx (stdio)

uvx --from git+https://<your-fork-url> monarch-mcp

(После того как вы запушете этот форк куда-нибудь — см. примечание в конце этого README о том, где в настоящее время находится этот код.)

obot, на основе Docker (streamable-http)

docker build -t monarch-mcp2-obot:local .
docker volume create monarch-session

docker run -d --rm \
  -p 8000:8000 \
  -v monarch-session:/data \
  -e MONARCH_EMAIL=you@example.com \
  -e MONARCH_PASSWORD=... \
  -e MONARCH_TOTP_SECRET=...  `# omit if your account doesn't use authenticator-app MFA` \
  monarch-mcp2-obot:local

Укажите в конфигурации MCP-сервера obot на основе Docker конечную точку streamable-http этого контейнера на порту 8000. Состояние сессии хранится в томе monarch-session, поэтому оно переживает перезапуски контейнера и повторные развёртывания без повторного входа.

Локальная разработка (stdio, без Docker)

uv sync
uv run monarch-mcp

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

uv run pytest
uv run ruff check src tests
uv run ruff format --check src tests
uv run mypy src/monarch_mcp/auth_runtime.py src/monarch_mcp/config.py \
  src/monarch_mcp/server.py src/monarch_mcp/groups/auth.py src/monarch_mcp/tool_metadata.py

(mypy --strict применяется только к файлам, которые этот форк создал или существенно изменил; унаследованные групповые модули не были повторно проверены на соответствие строгой типизации в рамках этого форка — см. ROADMAP.md.)

Где живёт этот код

Он был собран и проверен локально (установлен, протестирован и запущен — на обоих транспортах — при реальном рукопожатии MCP initialize), но в рамках этой работы не был запушен в размещённый git-remote. Запушьте его в свой собственный форк/remote, прежде чем указывать на него uvx --from git+..., и соответствующим образом обновите инструкции по Docker-сборке выше, если вы собираете из этого remote, а не из локальной копии.

Лицензия

MIT, унаследована от апстрима. См. LICENSE.