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

[English](README.en.md) · [Скачать 0.7.0rc2](https://github.com/finuchetai/finagent-mcp/releases/tag/v0.7.0rc2) · [PyPI](https://pypi.org/project/open-finance-mcp/0.7.0rc2/) · [Проверки](https://github.com/finuchetai/finagent-mcp/actions/workflows/tests.yml)

<!-- mcp-name: io.github.finuchetai/finagent-mcp -->

[**Посмотреть сервис «Финагент» →**](https://finuchetai.ru/?utm_source=github&utm_medium=opensource&utm_campaign=finance_mcp)

Автономный финансовый MCP от проекта «Финагент»: подключайте подготовленные отчёты
к своему локальному AI-ассистенту и задавайте вопросы о прибыли, движении денег и остатках.
Для самостоятельного запуска используйте инструкции ниже. Если нужна помощь с подключением
данных и управленческим учётом, [оставьте заявку на сайте сервиса](https://finuchetai.ru/?utm_source=github&utm_medium=opensource&utm_campaign=finance_mcp#lead-form).

Репозиторий: `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](AGENTS.md) и [поэтапной инструкции](docs/guided-setup.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-входа.
[Настройка и границы поддержки](docs/google-local-connect.md).
[Политика конфиденциальности](https://finuchetai.ru/privacy/).

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

Готовый комплект [finagent-google-codex-0.7.0rc2.zip](https://github.com/finuchetai/finagent-mcp/releases/download/v0.7.0rc2/finagent-google-codex-0.7.0rc2.zip)
доступен в [предварительном Release](https://github.com/finuchetai/finagent-mcp/releases/tag/v0.7.0rc2).
Это отдельный файл: архив `source.zip` и стандартные Source code архивы GitHub
не содержат `Start.cmd` и настроек Google-приложения автора.

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

Доступ Google ещё на проверке. При отказе или предупреждении о непроверенном
приложении остановитесь и передайте автору текст ошибки; обход предупреждения
не является шагом установки. Не отправляйте пароли, коды или токены.
Старая установка сохраняется отдельно; повторный запуск использует прежний профиль.
Таблица только читается. Подробности и ограничения — в [инструкции](docs/google-local-connect.md).

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

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

[Поэтапная настройка простыми словами](docs/guided-setup.md). Неполный ОПиУ, например
только до валовой прибыли, поддерживается с явно указанными ограничениями; отсутствие
чистой прибыли не требует выдумывать её или дополнять исходник нулями.

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

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

```sh
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`. Для работы агента с картой источника см.
[поэтапную настройку](docs/guided-setup.md). Установка из исходников и запуск тестов:

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

```sh
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. Структура конфигурации зависит от клиента; типовой фрагмент:

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

Рабочая папка клиента может быть любой: код установлен в venv, данных с относительными
путями нет. Проверка ниже использует настоящий subprocess из временной рабочей папки.
В 0.4.0 добавлен защищённый Streamable HTTP для удалённых клиентов и генератор
локального/удалённого плагина. [Выбор клиента и самостоятельное размещение](docs/connection-modes.md).
Для браузера потребуются сервер владельца, 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](LICENSE).
Правообладатель: Самойлова Татьяна. Репозиторий публичный; предварительный
выпуск 0.7.0rc2 опубликован. См. [порядок выпуска](docs/release-checklist.md).
SDK: [официальная документация stdio](https://py.sdk.modelcontextprotocol.io/run/).

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

Установите `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, права, обновление и полный прогон](docs/sources.md).

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

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

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

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

## Google Sheets (0.5.0)

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

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

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


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

[Сценарий и границы](docs/google-local-connect.md).
Готовый 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](https://pypi.org/project/open-finance-mcp/0.7.0rc2/)
доступны публично. В официальном [MCP Registry](https://registry.modelcontextprotocol.io/)
зарегистрирован `io.github.finuchetai/finagent-mcp`, версия 0.7.0rc2, статус active.
Запись запускает демо через `uvx`; реальные источники требуют отдельной настройки.
[Результат и порядок публикации](docs/registry-publication.md).