Финагент MCP — финансовые отчёты для AI-ассистента

English · Скачать 0.7.0rc2 · PyPI · Проверки

Автономный финансовый MCP от проекта «Финагент»: подключайте подготовленные отчёты к своему локальному AI-ассистенту и задавайте вопросы о прибыли, движении денег и остатках. Для самостоятельного запуска используйте инструкции ниже. Если нужна помощь с подключением данных и управленческим учётом, оставьте заявку на сайте сервиса.

Репозиторий: finagent-mcp. Имя устанавливаемого Python-пакета open-finance-mcp; команды запуска finance_mcp.server сохранены для совместимости с комплектом 0.3.0.

Текущая версия — 0.7.0rc2, предварительный выпуск: демо, адаптеры CSV/XLSX/PostgreSQL и Google Sheets, проверка среды и реестр кодов. Этот каталог целиком переносим: ему не нужны остальной репозиторий, база, домен, ключи или сервисы автора. Источник — вымышленная мастерская «Маяк», два закрытых месяца и один открытый. Даты фиксированы для воспроизводимости.

Что можно подключить

Источник	Что нужно	Зависит от Google
Демо	Установить пакет; свои данные не нужны	Нет
Excel (.xlsx), CSV	Карта подготовленных месячных отчётов и сверка с источником	Нет
PostgreSQL	Согласованные представления, карта данных, роль только на чтение и сверка	Нет
Google Sheets	OAuth-вход и поддерживаемый формат месячного отчёта	Да; проверка доступа ещё рассматривается

Карту и техническую настройку можно поручить своему агенту по AGENTS.md и поэтапной инструкции. Поддержка PostgreSQL не означает поддержку MySQL или Microsoft SQL Server. Примеры вопросов: «Как изменилась выручка?», «Каковы поступления и выплаты за месяц?», «Чем объясняется отличие прибыли от движения денег?» Ответы ограничены доступными отчётами и их методикой. Из одной выписки прибыль не выводится.

Статус Google-подключения

Локальное чтение ДДС через Google Sheets в Codex на Windows проверено у владельца и внешнего тестировщика, включая повторное подключение после перезапуска Codex. 14.11.2026 оформление Google-приложения проверено и опубликовано; заявка на проверку доступа к таблицам находится на рассмотрении Google. Массовый Google-вход пока не объявляется одобренным.

Обычный git clone не включает зарегистрированную OAuth-конфигурацию приложения или готовый Windows-комплект с Start.cmd. Google-подключение требует отдельно полученного комплекта автора либо Desktop-конфигурации через FINANCE_GOOGLE_OAUTH_APP. Демо работает без Google-входа. Настройка и границы поддержки. Политика конфиденциальности.

Установка Google Sheets в Codex на Windows

Готовый комплект finagent-google-codex-0.7.0rc2.zip доступен в предварительном Release. Это отдельный файл: архив source.zip и стандартные Source code архивы GitHub не содержат Start.cmd и настроек Google-приложения автора.

Установите Codex CLI и Python 3.11 или новее. Нужен доступ к интернету.
Скачайте Windows-комплект и полностью распакуйте его в отдельную папку.
Запустите Start.cmd: войдите в Google, укажите ссылку на свою таблицу, выберите отчёт и месяц, подтвердите валюту и денежные единицы.
После успешной настройки перезапустите Codex и откройте новый чат. Попросите: «Прочитай паспорт и доступные месяцы финансового MCP, затем разбери мой отчёт».

Доступ Google ещё на проверке. При отказе или предупреждении о непроверенном приложении остановитесь и передайте автору текст ошибки; обход предупреждения не является шагом установки. Не отправляйте пароли, коды или токены. Старая установка сохраняется отдельно; повторный запуск использует прежний профиль. Таблица только читается. Подробности и ограничения — в инструкции.

Если вы устанавливаете MCP через ассистента

Передайте ему: «Прочитай AGENTS.md и docs/guided-setup.md. Сначала спроси, где я хочу работать: браузер, настольный ChatGPT или другой клиент. Веди меня по одному шагу, объясняй термины и выполняй техническую настройку сам. Не задавай все вопросы о данных одной анкетой. Сначала посмотри разрешённый источник и объясни, что можно подключить».

Поэтапная настройка простыми словами. Неполный ОПиУ, например только до валовой прибыли, поддерживается с явно указанными ограничениями; отсутствие чистой прибыли не требует выдумывать её или дополнять исходник нулями.

Быстрый запуск

Пакет опубликован в PyPI. Для установки без клонирования репозитория:

python3 -m venv .venv
.venv/bin/python -m pip install 'open-finance-mcp[files,postgres]==0.7.0rc2'
.venv/bin/python -m finance_mcp.diagnostics stdio --timeout 15

Без конфигурации запускается вымышленное демо. На Windows используйте python и .venv\Scripts\python.exe. Для работы агента с картой источника см. поэтапную настройку. Установка из исходников и запуск тестов:

Нужен Python 3.11+ с venv/pip и доступ к индексу Python-пакетов при первой установке. Скопируйте только этот каталог в отдельное место. Внутри копии:

python3 preflight.py environment
python3 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/python -m finance_mcp.diagnostics stdio --timeout 15
.venv/bin/python -m unittest discover -s tests -p test_demo.py -v
.venv/bin/open-finance-mcp

Последняя команда ждёт сообщений MCP на stdin; пустой экран — нормально. Завершение: Ctrl+C. Сервер запускается помощником как дочерний процесс; отдельный фоновой сервис и открытый порт ему не нужны. На Windows используйте .venv\Scripts\python.exe.

Подключение к локальному агенту

В настройках MCP клиента, поддерживающего stdio, укажите абсолютный путь к Python созданной venv. Структура конфигурации зависит от клиента; типовой фрагмент:

{
  "mcpServers": {
    "finance-demo": {
      "command": "/absolute/path/to/demo/.venv/bin/python",
      "args": ["-m", "finance_mcp.server"]
    }
  }
}

Рабочая папка клиента может быть любой: код установлен в venv, данных с относительными путями нет. Проверка ниже использует настоящий subprocess из временной рабочей папки. В 0.4.0 добавлен защищённый Streamable HTTP для удалённых клиентов и генератор локального/удалённого плагина. Выбор клиента и самостоятельное размещение. Для браузера потребуются сервер владельца, HTTPS и настроенный OAuth-провайдер; публикация кода сама по себе их не создаёт.

Передайте агенту: «Прочитай AGENTS.md, установи этот пакет в отдельную venv, выполни проверки и помоги добавить stdio MCP в мой локальный клиент. Покажи прибыль и остаток денег за сентябрь 2026 и объясни, почему прибыль отличается от движения денег».

Ожидаемо: прибыль сентября 75000.00 RUB, движение денег 80000.00 RUB, остаток на конец 155000.00 RUB. Это учебные числа; сначала прочитайте паспорт.

Интерфейс адаптера (контракт 1.1)

finance_mcp.contract.FinanceAdapter — Python Protocol без зависимости от MCP SDK:

passport() -> str: подтверждённая методика и ограничения одного клиента;
periods() -> tuple[Period, ...]: периоды и доступные отчёты;
report(kind, month) -> Report: ОПиУ, ДДС или остатки;
notes(month) -> str: примечания закрытого периода.

Собственный адаптер передаётся в finance_mcp.server.create_server(adapter). Сервер не знает SQL, таблиц и файлов источника. Без --config CLI запускает DemoAdapter; подключение CSV/XLSX/PostgreSQL выбирается через --config. Контракт не является механизмом авторизации: будущий адаптер обязан обеспечивать права на стороне источника.

Report: тип, период, валюта ISO-кодом, источник, as_of (подтверждённая дата состояния с TZ или null), отдельные received_at / as_of_status / source_time_raw, complete и непустой tuple строк. Строка: устойчивый code, название, разрез, Decimal и статус value/missing/not_applicable. Последние два означают None, в JSON — null, и отличаются от денежного нуля. Пропуск требует complete=false. Уникальность строки — (code, dimension). Итоги имеют собственные коды; правила сложения описывает паспорт, инструмент не складывает строки и не конвертирует валюты. Разные отчёты могут иметь разные валюты, это всегда явно в ответе каждого отчёта.

FinanceService проверяет запрос целиком до загрузки отчётов: 1–12 уникальных периодов, закрытость и доступность отчёта; неверный запрос отклоняется, частичного успешного ответа нет. Проверяется соответствие возвращённого отчёта запросу. Деньги сериализуются строками; ответ — один текстовый JSON без дублирования в structuredContent.

Проверки и границы готовности

Тесты сверяют все 24 строки демо, денежные тождества и разные смыслы нуля/пропуска, подставляют второй адаптер через публичный интерфейс, проверяют отказ на открытый, отсутствующий и испорченный период. Интеграция запускает установленный сервер по stdio, делает initialize/list_tools и вызывает все шесть инструментов, включая отрицательные сценарии и повторный запуск. Никаких подключений к реальным финансовым системам нет.

Перенос: скопируйте preflight.py, README.md, AGENTS.md, pyproject.toml, src/, tests/, docs/ и examples/. Не переносите .venv, build, *.egg-info, кэши или настройки исходного проекта. Удаление установки: остановите MCP в клиенте, уберите его конфигурацию, удалите копию пакета и venv. Секретов и внешних ресурсов это демо не создаёт.

Для публичного выпуска выбрана лицензия MIT; текст — LICENSE. Правообладатель: Самойлова Татьяна. Репозиторий публичный; предварительный выпуск 0.7.0rc2 опубликован. См. порядок выпуска. SDK: официальная документация stdio.

Источники клиента

Установите pip install '.[files,postgres]' внутри venv. Примеры вымышленного клиента «Липа» — examples/lipa: 40 строк, 7 отчётов, две точки. Проверка CSV: python -m finance_mcp.server --config examples/lipa/csv.json --check. В аргументы MCP-клиента добавьте --config и абсолютный путь к JSON. Формат экспорта, Excel, PostgreSQL, права, обновление и полный прогон.

Проверка среды, короткая stdio-проба, даты и постоянные коды. Примеры в examples/lipa: csv-registry.json для реестра и csv-dates.json для неизвестной даты состояния. Шаблон акта сверки фиксирует границы приёмки и согласование владельца; тесты его не подписывают.

Обратная связь и участие

Ошибки описывайте по шаблону, без реальных финансовых данных, персональных сведений и секретов. Инструкция по изменениям: CONTRIBUTING.md. Уязвимости: SECURITY.md. История: CHANGELOG.md.

Самостоятельное использование MCP не требует регистрации в сервисе «Финагент». Ссылка на сервис помогает найти команду проекта и получить помощь с подключением.

Google Sheets (0.5.0)

Прямое чтение одной выбранной книги сервисным аккаунтом владельца и обновление через refresh_source. Оригинал не меняется. Поддерживаются нормализованные диапазоны и согласованная карта широкого отчёта. См. инструкцию. Live-приёмка сервисного аккаунта остаётся отдельным обязательным этапом.

Вход Google без сервисного аккаунта (0.6.0)

Основной путь: агент запускает finance-mcp-google login, пользователь разрешает чтение в Google и указывает таблицу. Токены — в хранилище ОС; MCP автоматически обновляет данные перед отчётами. Автору нужно один раз зарегистрировать OAuth app; зарегистрированные настройки отдельно передаются автором, в репозитории их нет. См. подключение и подготовку приложения. Проверен сценарий чтения ДДС в реальном интерфейсе Codex на Windows; поддержка других клиентов и способов входа этим не подтверждается. Для подключения не требуется изменять ячейки.

Кандидат 0.7.0rc2: Google Sheets и локальный Codex

Сценарий и границы. Готовый Windows-комплект из Release запускается через Start.cmd: Google-вход, ссылка, автокарта, проверка stdio и регистрация Codex. Агент может использовать python -m finance_mcp.local_setup. Требуются Codex и Python3.11+; первоначальная установка зависимостей использует сеть. Упаковка, Windows-bootstrap и чтение ДДС в Codex проверены. Массовый доступ Google на проверке. Остатки поддержаны технически, но их отдельная пользовательская приёмка не заявляется; для этого предварительного выпуска она исключена владельцем.

0.7.0rc2 поддерживает существующие ДДС с итоговой колонкой и остатки со счётом/показателем и числовыми датами Google. Отдельная тестовая книга, копия и изменение ячеек не нужны. Полный охват и ограничения: docs/google-local-connect.md.

Каталоги MCP

GitHub Release и Python-пакет 0.7.0rc2 доступны публично. В официальном MCP Registry зарегистрирован io.github.finuchetai/finagent-mcp, версия 0.7.0rc2, статус active. Запись запускает демо через uvx; реальные источники требуют отдельной настройки. Результат и порядок публикации.

finagent-mcp

Documentation