stockdata-mcp

MCP-сервер для исследования акций. Два бэкенда, одна поверхность инструментов.

Разделение намеренное. Qualtrim — клиент FMP: он покупает сырые данные и добавляет свой слой. Поэтому этот сервер обращается к FMP напрямую за всем сырым, а вызовы Qualtrim тратит только на то, что уникально принадлежит Qualtrim.

52 инструмента — 30 FMP, 22 Qualtrim.

Прежде чем включать бэкенд Qualtrim

Половина FMP этого сервера — обычная: документированный публичный API, ключ, который вы регистрируете, используйте как угодно.

Половина Qualtrim — не обычная. Qualtrim не публикует API — эти маршруты были прочитаны из их поставляемого JavaScript, а их Условия предоставления услуг запрещают как обратную разработку платформы, так и использование автоматизированных средств для получения данных с неё без предварительного письменного согласия.

Это согласие не передаваемо, и данный репозиторий его не предоставляет. Если вы хотите запускать бэкенд Qualtrim, вам нужна собственная платная учётная запись Qualtrim и собственное письменное разрешение от Qualtrim, полученное вами самостоятельно. Спрашивайте их напрямую по адресу support@qualtrim.com.

Без этого запускайте сервер с незаданными QUALTRIM_USERNAME/QUALTRIM_PASSWORD. Инструменты FMP отлично работают сами по себе, и ничто здесь не зависит от Qualtrim.

Код публикуется как справочный пример того, как устроен такой клиент, а не как приглашение направлять его на чужой сервис. Заявленное средство Qualtrim для нарушений — закрытие учётной записи, а их сборы не возвращаются.

Установка

cd ~/Projects/stockdata-mcp
uv venv && uv pip install -e .
./scripts/set-credentials.sh          # prompts; password input is hidden

set-credentials.sh записывает .env с правами 0600. Он в .gitignore. Получите бесплатный ключ FMP на https://site.financialmodelingprep.com/developer/docs.

Зарегистрируйтесь один раз, для каждого сеанса на машине:

claude mcp add stockdata --scope user -- ~/Projects/stockdata-mcp/.venv/bin/stockdata-mcp

Без флагов -e — сервер сам читает .env, поэтому учётные данные не попадают в ~/.claude.json. Настоящие переменные окружения по-прежнему переопределяют файл, так что MCP-клиент может передать -e, если хотите.

Проверьте из любого сеанса с помощью backend_status.

Рекомендации для модели

Сервер поставляет собственные инструкции по использованию через протокол MCP — выбор бэкенда, лимиты бесплатного тарифа, особенности Qualtrim, как сообщать цифры. Каждый MCP-клиент получает их автоматически, без дополнительной настройки.

Также есть более полный навык в .claude/skills/stock-research/, охватывающий исследовательские рабочие процессы глубже. Claude Code читает его из ~/.claude/skills/ (создайте там симлинк). Claude Desktop управляет навыками в своём собственном расположении и не подхватит его из этого каталога — он полагается на инструкции сервера, указанные выше, которые содержат критически важные для принятия решений части.

Related MCP server: StocksMCP

Кэширование и бюджет

Ответы кэшируются в хранилище SQLite по пути ~/.cache/stockdata-mcp/cache.db. Хранилище глобальное, не для каждого клиента — каждый процесс сервера для этого пользователя открывает один и тот же файл, поэтому Claude Code и Claude Desktop используют один кэш и один дневной итог. Это необходимо для корректности, а не только для эффективности: квота FMP принадлежит ключу API, и оба приложения используют один и тот же ключ.

TTL выбирается для каждой конечной точки. Котировки живут минуту; профили — неделю; справочные данные — месяц. Исторические бары, диапазон дат которых закончился до сегодняшнего дня, никогда не истекают, потому что закрытие, которое уже произошло, не может измениться. Диапазон, доходящий до сегодняшнего дня, всё ещё имеет движущийся край и получает 15 минут.

Три инструмента управляют этим:

estimate_cost существует потому, что соотношение инструмент-запрос не 1:1 и невидимо со стороны вызывающего: fmp_search выполняет 2 запроса, fmp_price_target — 3, а fmp_quote — по одному на символ на бесплатном ключе. Он сообщает наихудшее количество запросов, сколько этапов уже закэшировано, и чистый результат против сегодняшнего оставшегося бюджета. Проверено: его прогноз точно совпал с фактическими расходами на смешанном плане из пяти вызовов и вернул 0 для того же плана, повторно запущенного в тёплом кэше.

Измерено на шести независимых процессах, запрашивающих один и тот же символ одновременно: 1 запрос к источнику, 5 попаданий в кэш, без конкуренции за блокировки.

Конфигурация

Инструменты FMP

Поиск и справочники: fmp_search, fmp_profile, fmp_quote, fmp_peers, fmp_reference.

Фундаментальные показатели: fmp_income_statement, fmp_balance_sheet, fmp_cash_flow, fmp_key_metrics, fmp_ratios, fmp_financial_growth, fmp_financial_scores, fmp_revenue_segmentation, fmp_enterprise_values.

Аналитики и оценка: fmp_analyst_estimates, fmp_price_target, fmp_grades, fmp_dcf.

События и рынки: fmp_dividends, fmp_earnings, fmp_earnings_calendar, fmp_historical_prices, fmp_technical_indicator, fmp_screener, fmp_market_movers, fmp_sector_performance, fmp_insider_trading, fmp_news.

fmp_request(endpoint, params) достигает любой из ~250 стабильных конечных точек FMP — ETF-холдинги, 13F, сделки сенаторов, экономические индикаторы, документы SEC, стенограммы — без отдельной обёртки.

Что на самом деле покрывает бесплатный тариф

Проверено на живом бесплатном ключе: работают 22 из 29 инструментов.

Требуется платный план: fmp_screener, fmp_reference, fmp_news, fmp_insider_trading, fmp_technical_indicator. Каждый возвращает понятную ошибку, называющую план как причину.

Два примечания:

• Многосимвольный fmp_quote переключается на запросы по каждому символу, потому что пакетный маршрут платный. Ограничено 20 символами для защиты дневной квоты.

• Платность fmp_technical_indicator легко обойти — fmp_historical_prices бесплатен, поэтому индикаторы можно вычислять из OHLCV локально.

Бесплатный тариф позволяет примерно 250 запросов/день. Передавайте limit и from_date/to_date; по умолчанию для истории цен — весь ряд.

Инструменты Qualtrim

По символу: qualtrim_overview, qualtrim_profile, qualtrim_quote, qualtrim_dcf, qualtrim_kpi_charts, qualtrim_chart, qualtrim_ai_analysis, qualtrim_analyst_estimates.

Сравнение: qualtrim_available_kpis, qualtrim_compare.

Ваша учётная запись: qualtrim_portfolios, qualtrim_portfolio, qualtrim_portfolio_look_through_earnings, qualtrim_portfolio_ai_analysis, qualtrim_portfolio_dividends, qualtrim_watchlists, qualtrim_watchlist, qualtrim_dip_finder, qualtrim_watchlist_valuation_ranges.

Запасной выход: qualtrim_request(path), только GET.

Записи (qualtrim_add_watchlist_stock, qualtrim_add_portfolio_holding) отказываются выполняться, если QUALTRIM_ENABLE_WRITES=true не задан.

Как на самом деле работает аутентификация Qualtrim

Их поставляемый бандл выглядит как аутентификация по bearer-токену — authTokens в localStorage, Authorization: Bearer. Это не так. Вход возвращает объект пользователя и устанавливает cookie сессии Express (connect.sid); именно этот cookie авторизует обычные запросы. Путь токена в бандле используется только его вызовом обновления.

Этот клиент хранит jar-файл cookie, кэширует сессию в ~/.cache/stockdata-mcp/qualtrim-session.json (0600) и автоматически входит снова при получении 401.

Известное расхождение

Их развёрнутый бэкенд уже разошёлся с бандлом, из которого были прочитаны маршруты:

Оба инструмента уже используют рабочие варианты. Ожидайте большего со временем — 404 от инструмента Qualtrim означает, что маршрут переместился, а не что тикер неверен.

Пустой результат qualtrim_dcf — не сбой; это означает, что для этого символа в вашей учётной записи не сохранён DCF.

Qualtrim и их Условия предоставления услуг

Qualtrim не публикует API. Эти маршруты были прочитаны из их поставляемого JavaScript. Два следствия:

Это может сломаться без предупреждения. См. «Известное расхождение» выше — так уже и было.

Это ограничено их условиями. Их раздел о допустимом использовании запрещает использование автоматизированных средств для систематического получения данных с сайта без предварительного письменного согласия, а также отдельно запрещает обратную разработку платформы. Их рычаг принуждения — закрытие учётной записи, и их сборы не возвращаются.

Согласие получить можно — запрет обусловлен им. Спрашивайте Qualtrim напрямую по адресу support@qualtrim.com и сохраняйте их ответ.

Здесь настройки по умолчанию консервативны: 1 запрос/сек, максимум 2 одновременных, пользовательский агент, соответствующий браузеру, GET по умолчанию, без массового перечисления. Держитесь объёмов интерактивного исследования.

Структура

src/stockdata_mcp/
  server.py     tool definitions for both backends
  fmp.py        FMP stable-API client
  qualtrim.py   Qualtrim cookie-session client
  util.py       throttling, response trimming, .env loading
scripts/
  set-credentials.sh
.claude/skills/stock-research/SKILL.md

Не инвестиционная рекомендация

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