okama-mcp: подключаем ИИ-ассистента к портфельной аналитике по Model Context Protocol

ИИ-ассистенты — ChatGPT, Claude, Gemini — бойко рассуждают о финансах, но числа любят галлюцинировать: то перепутают CAGR портфеля, то сошлются на статистику, которой нет. Причина банальна — LLM генерирует правдоподобный текст, а не считает по рыночным данным. okama-mcp закрывает этот разрыв: это MCP-сервер, который отдаёт ассистенту инструментарий библиотеки okama для портфельного анализа. Ассистент перестаёт выдумывать и на каждый запрос дёргает настоящий расчёт — бэктест, Монте-Карло, границу эффективности — и возвращает числа с графиком.

Мы уже писали на Хабре про библиотеку okama и веб-интерфейс okama.io. okama-mcp — следующий логичный шаг той же линии: движок один и тот же, но теперь к нему ходит не человек из Python-кода и не через веб-виджеты, а LLM-ассистент по стандартному протоколу. Проект бесплатный, open-source под MIT, собран на FastMCP, Python ≥ 3.11.

Зачем здесь MCP

Model Context Protocol — открытый стандарт от Anthropic для подключения LLM к внешним инструментам и данным. По сути это транспорт плюс схема для tool-use: ассистент видит список тулов с их JSON-схемами, по ходу диалога решает, какой вызвать, шлёт аргументы, получает результат и вплетает его в ответ. Программу, которая эти тулы предоставляет, называют MCP-сервером. okama-mcp — ровно такой сервер: оборачивает okama в набор тулов и говорит на MCP.

Профит в том, что ассистенту не нужно «знать» финансовую математику и свежие котировки — он делегирует расчёт okama и работает как оркестратор: разобрал запрос на естественном языке → выбрал и вызвал нужный тул → объяснил результат словами.

Как это устроено

Под капотом — FastMCP, один кодовый базис и два транспорта:

• stdio — для локальных клиентов (Claude Desktop, Claude Code, Cursor, Codex). Клиент поднимает сервер как дочерний процесс и общается по stdin/stdout.

• streamable-http — для self-hosting: поднимаете сервер на своём хосте и подключаете по сети.

Несколько решений, важных для тех, кто полезет внутрь:

• Тулы stateless. Никакой сессии — полная спецификация портфеля передаётся в каждом вызове. Это упрощает и кэширование, и self-hosting: любой инстанс обслужит любой запрос.

• Кэш по контент-хэшу. Дорогие okama-объекты (Portfolio, EfficientFrontier) кэшируются по sha256 от канонизированной спеки (TTL + LRU). Повторные вызовы на ту же спеку отдаются мгновенно.

• Типизированные спеки на pydantic. Сложные тулы принимают не плоский список параметров, а валидируемые структуры — PortfolioSpec, MCSpec, CashflowSpec, FrontierSpec. Кривой аргумент отлетает с внятной ошибкой ещё до вызова okama.

• Вложенные портфели. Везде, где принимается список активов, элементом может быть тикер или вложенный портфель той же формы. Так портфель 60/40 кладётся на границу эффективности как единый компонент или сравнивается с золотом.

• Графики как MCP image content. Каждый plot_*-тул рендерит PNG (по умолчанию 1500×900) и возвращает его как image content — Claude Desktop рисует инлайн. Для клиентов без инлайн-картинок (терминальный Claude Code) есть save_path.

Где работает, а где — нет

Главный практический нюанс — прямое следствие транспорта stdio: локальный клиент запускает сервер как процесс на вашей машине. Отсюда правило: работает там, где ассистент — это приложение на ПК, и не работает там, где он живёт только в браузере и не может запустить процесс на устройстве.

Готового публичного endpoint у проекта нет намеренно: дизайн — «запусти у себя», локально через uvx или на своём сервере. Нужен remote — это okama-mcp http за nginx/TLS (готовые конфиги лежат в deploy/).

Что можно спросить — с примерами

Общение идёт обычным языком: ассистент сам решает, какой тул дёрнуть. Ниже — основные сценарии и готовые промпты, которые можно скопировать.

Поиск активов и сравнение. Найти тикер фонда или индекса, посмотреть историю и дивиденды, сравнить несколько активов по доходности, риску и корреляциям — в том числе против бенчмарка.

Найди тикер фонда на золото и ETF на индекс S&P 500

Покажи дивидендную историю по фонду недвижимости VNQ за 10 лет

Сравни SPY, GLD и BND: доходность, риск и корреляции

Бэктест портфеля. Прогон портфеля по истории: доходность, волатильность, просадки, VaR/CVaR.

Сделай бэктест портфеля 60% акций / 40% облигаций с 2010 года и покажи просадки

Сравни мой портфель с рынком: CAGR, волатильность, максимальная просадка

Посчитай исторический VaR и CVaR для портфеля 70/30

Монте-Карло и планирование изъятий. Главный сценарий для пенсионного планирования: форвардная симуляция с пополнениями и изъятиями. На выходе — перцентильный коридор капитала, распределение IRR и оценка, на сколько лет хватит денег.

Прогноз Монте-Карло: вывожу 50 000 ₽/мес с индексацией на инфляцию 25 лет — хватит ли капитала?

Какую сумму можно безопасно изымать, чтобы денег хватило на 30 лет?

На сколько лет хватит портфеля при изъятии 5% в год?

Диагностика распределений. Для тех, кто помнит про тяжёлые хвосты: реальные просадки случаются чаще, чем обещает нормальное распределение. Ассистент подгонит распределение к эмпирическим доходностям и покажет, какая модель описывает их лучше.

Насколько доходности моего портфеля отклоняются от нормального распределения?

Какое распределение лучше описывает мои данные — нормальное или Student-t?

Покажи гистограмму доходностей с подогнанной кривой

Граница эффективности. Подбор оптимального сочетания активов по соотношению доходности и риска — с весами по каждой точке.

Построй границу эффективности для SPY, BND и GLD

Найди портфель с максимальным коэффициентом Шарпа при безрисковой ставке 3%

Покажи портфель с минимальным риском и его веса

Макро. Инфляция, ставки центробанков, макроиндикаторы по странам.

Покажи инфляцию доллара за последние 10 лет

Какая сейчас ключевая ставка ФРС и ЦБ РФ?

Графики. Почти у каждого расчёта есть графическая версия — от кривой капитала и просадок до QQ-плота и карты переходов весов вдоль границы эффективности. PNG приходит прямо в чат.

Нарисуй график роста капитала моего портфеля с учётом инфляции

Установка

Самый ленивый способ — попросить самого ассистента: «установи MCP okama». В Claude Code с включённым auto mode (у Cursor и Codex есть аналоги) он сам пропишет конфиг.

Вручную — проще всего через uv или pipx, без клонов и venv:

uvx okama-mcp stdio        # прямо из PyPI
# или
pipx install okama-mcp

pip install okama-mcp тоже работает, но на современных Linux система с PEP 668 (externally-managed) завернёт pip вне venv. Тогда заводите отдельный venv и прописывайте в конфиге клиента абсолютный путь к скрипту okama-mcp: GUI-клиенты не видят ваш shell-PATH. uvx/pipx это снимают, изолируя установку сами.

Подключение клиентов:

// Claude Desktop — claude_desktop_config.json
{ "mcpServers": { "okama": { "command": "uvx", "args": ["okama-mcp", "stdio"] } } }

# Claude Code — глобально, из любой директории
claude mcp add --scope user okama -- uvx okama-mcp stdio

# Codex
codex mcp add okama -- uvx okama-mcp stdio

Cursor — тот же блок mcpServers в .cursor/mcp.json. После перезапуска клиента okama появляется в списке тулов.

Self-hosting:

okama-mcp http --host 127.0.0.1 --port 8765 --path /mcp

затем http://<server>:8765/mcp в клиенте; в прод — за nginx + TLS (примеры systemd-юнита и nginx-vhost — в deploy/).

Безопасно ли и сколько стоит

• Бесплатно, MIT, без регистрации и хостед-сервиса — вы запускаете сервер сами.

• Stateless и локально: портфель описывается словами прямо в чате, никаких личных кабинетов и брокерских доступов. При self-host save_path и данные остаются на вашем сервере.

• Прозрачно: ассистент опирается на расчёты okama, а не на память модели, поэтому числам можно доверять и перепроверять их тем же тулом.

Ссылки

• Проект: github.com/mbk-dev/okama-mcp

• PyPI: pypi.org/project/okama-mcp

• Сайт MCP: mcp.okama.io

• Библиотека okama: github.com/mbk-dev/okama

• Сообщество okama: community.okama.io

• Курс: «Профессиональное создание инвестиционного портфеля»

Вопросы, баг-репорты и пул-реквесты приветствуются — проект открытый.