API ВЕГА
English

MCP-сервер FinancialFilings

Официальный сервер Model Context Protocol (MCP) для API FinancialFilings. Прямой доступ из Claude и любого совместимого с MCP клиента к нормативной отчётности, финансовым данным и корпоративной информации публичных компаний по всему миру. По умолчанию доступны 17 отобранных инструментов (установите MCP_FULL_SURFACE=1, чтобы включить полный набор из 55 инструментов). Бесплатно для всех пользователей FinancialFilings. Данные поступают от официальных регулирующих органов.

Быстрый старт

Если вы аналитик, исследователь или просто хотите задавать Claude вопросы об отчётности публичных компаний:

  • Создайте бесплатный аккаунт на financialfilings.com — MCP-коннектор бесплатен для всех пользователей FinancialFilings. Платный план не требуется.

  • Добавьте коннектор в свой MCP-клиент — выберите его в разделе «Подключение клиента» ниже. Два наиболее распространённых варианта:

    • Claude.ai / Claude Desktop: Settings → Connectors → Add custom connector → URL: https://mcp.financialfilings.com/mcp

    • Claude Code: claude mcp add --transport http financialreports https://mcp.financialfilings.com/mcp

  • Войдите в аккаунт FinancialFilings, когда появится соответствующий запрос. Готово.

Подробная инструкция по настройке со снимками экрана: financialfilings.com/integrations/claude/.

Подключение клиента

Это удалённый MCP-сервер, использующий Streamable HTTP и OAuth (PKCE + Dynamic Client Registration). Копировать API-ключ и хранить секреты не нужно: при подключении откроется браузер для входа в аккаунт FinancialFilings.

Конечная точка: https://mcp.financialfilings.com/mcp

Найдите свой клиент ниже. Если его нет в списке, используйте универсальный блок в конце раздела: конечная точка и поток OAuth одинаковы для всех клиентов, отличается только файл конфигурации.

Claude.ai / Claude Desktop

Settings → Connectors → Add custom connector → URL: https://mcp.financialfilings.com/mcp. Войдите в аккаунт, когда появится соответствующий запрос.

Claude Code

claude mcp add --transport http financialreports https://mcp.financialfilings.com/mcp

Выполните /mcp в текущем сеансе, чтобы завершить вход через браузер.

Codex (OpenAI)

Codex использует TOML. Добавьте конфигурацию в ~/.codex/config.toml (или в файл проекта .codex/config.toml):

[mcp_servers.financialreports]
url = "https://mcp.financialfilings.com/mcp"

Затем пройдите аутентификацию — Codex запускает поток OAuth в браузере для серверов, которые его поддерживают:

codex mcp login financialreports

Cursor

Установите сервер одним нажатием из каталога Cursor или добавьте его вручную в ~/.cursor/mcp.json (для всех проектов) либо .cursor/mcp.json (для отдельного проекта):

{
  "mcpServers": {
    "financialfilings": { "url": "https://mcp.financialfilings.com/mcp" }
  }
}

При первом использовании OAuth запустится в браузере.

Kilo Code

Файл проекта .kilocode/mcp.json (или глобальный файл настроек MCP):

{
  "mcpServers": {
    "financialreports": {
      "type": "remote",
      "url": "https://mcp.financialfilings.com/mcp"
    }
  }
}

opencode

Файл opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "financialreports": {
      "type": "remote",
      "url": "https://mcp.financialfilings.com/mcp",
      "enabled": true
    }
  }
}

Gemini CLI

Файл ~/.gemini/settings.json:

{
  "mcpServers": {
    "financialreports": { "httpUrl": "https://mcp.financialfilings.com/mcp" }
  }
}

Hermes

Добавьте сервер в раздел mcp_servers конфигурации Hermes в формате YAML:

mcp_servers:
  financialreports:
    url: "https://mcp.financialfilings.com/mcp"
    auth: oauth

Универсальная настройка (для любого MCP-клиента)

Большинство MCP-клиентов поддерживают объект mcpServers. Укажите в нём конечную точку, используя Streamable HTTP:

{
  "mcpServers": {
    "financialreports": {
      "type": "streamable-http",
      "url": "https://mcp.financialfilings.com/mcp"
    }
  }
}

Клиенты со встроенной поддержкой OAuth для удалённых MCP-серверов (Claude, Cursor, Windsurf, VS Code, opencode, а также Codex через codex mcp login) автоматически запускают вход через браузер. Для OpenClaw и других MCP-клиентов используйте этот блок с URL коннектора и пройдите OAuth, когда появится запрос. Точное расположение файла конфигурации смотрите в документации MCP для вашего клиента.

Устранение неполадок: «Client Not Registered»

Если при входе открывается страница Client Not Registered с сообщением «The client ID … was not found in the server's client registry», значит, клиент использует регистрацию, которой больше нет на сервере.

Удалите коннектор и добавьте его снова. Это единственный способ устранить проблему, и он займёт всего несколько секунд:

КлиентЧто нужно сделать
ChatGPT / OpenAIОткройте Settings → Connectors, удалите FinancialFilings (если вы подключили его до переименования, в списке он может называться FinancialReports), затем добавьте его снова по адресу https://mcp.financialfilings.com/mcp и войдите в аккаунт.
Claude.ai / Claude DesktopОткройте Settings → Connectors, удалите FinancialFilings (если вы подключили его до переименования, в списке он может называться FinancialReports), добавьте коннектор снова и войдите в аккаунт.
Claude Code / Codex / Cursor / opencodeУдалите сервер и добавьте его заново (например, выполните claude mcp remove financialreports, а затем повторно добавьте сервер) или снова запустите команду входа клиента (codex mcp login financialreports).

На странице с ошибкой не указаны две важные детали:

  • Ошибка не исчезнет сама, а повторная попытка не поможет. Вход выполняется в браузере, поэтому клиент не узнаёт о сбое: он ждёт callback, который так и не приходит, и повторно использует тот же недействительный ID. Перезапуск тоже не поможет: размещённые коннекторы (ChatGPT, Claude.ai) хранят регистрацию на сервере, поэтому удалить её можно только удалив сам коннектор.

  • С аккаунтом всё в порядке, данные не затронуты. При повторном добавлении создаётся новая регистрация, после чего всё работает как прежде.

Если проблема возникла 14 июля 2026 года или позже: при переключении кэш-системы сохранённые регистрации клиентов были потеряны. С тех пор вход выполняется в обычном режиме — описанная выше процедура удаления и повторного добавления нужна только для коннекторов, добавленных до этой даты.

Что входит в сервер

По умолчанию доступны 17 инструментов для вызова через LLM — тщательно отобранный набор для решения практических задач аналитиков:

ОбластьИнструментыПримеры использования
Компании5Поиск по названию, тикеру или ISIN, получение полных профилей компаний и нормализованных финансовых данных, прогноз даты следующего годового отчёта, сопоставление списка идентификаторов с ID компаний
Отчётность4Просмотр списка документов, получение отчётности и её содержимого в формате markdown (до 150K символов), поиск по ключевым словам в отдельном документе
ISIN2Поиск по ISIN, просмотр компаний с двойным листингом
Справочная таксономия2Категории и типы отчётности
Аккаунт1Просмотр расходов на API и MCP за текущий период, лимитов расходов и оставшихся бесплатных кредитов (бесплатно, плата не взимается)
Справочные материалы3Таксономия типов отчётности, классификация отраслей ISIC и рекомендации по получению данных в формате markdown — доступны для вызова клиентами, работающими только с инструментами и не умеющими читать MCP-ресурсы

Установите MCP_FULL_SURFACE=1, чтобы вернуть полный набор из 55 инструментов: иерархию разделов, подразделений, групп и классов ISIC; остальные справочные данные (страны, языки, источники, определения строк финансовой отчётности и история подач); пользовательские списки наблюдения; подписки на webhook; журнал аудита объединения компаний; списки ценных бумаг по биржам; конечные точки для настройки аккаунта агентом (регистрация, получение ключа, смена ключа, ссылка на оплату, подтверждение владельца, проверка статуса); исходную конечную точку filings_markdown_search_retrieve, на которой основан filings_markdown_search; а также filings_document_retrieve (возвращает файл, а не JSON).

Поставляемый набор инструментов формируется на основе зафиксированного и проверенного снимка схемы OpenAPI FinancialFilings (scripts/openapi.snapshot.json, закреплённого с помощью FR_PIN_SCHEMA=1 в CI и при сборке Docker). Благодаря этому результат воспроизводим и не меняется незаметно при повторной сборке.

Дополнительный skill

В репозитории есть Agent Skill financial-filings-research. Он помогает Claude объединять эти инструменты в рабочие процессы, которыми пользуются аналитики: поиск компаний, подготовка сводок по отчётности, сравнение финансовых показателей нескольких компаний, анализ отраслей ISIC и мониторинг отчётности. Skill активируется автоматически, когда пользователь упоминает название компании, тикер, ISIN, тип отчётности или финансовый показатель.

Архитектура

┌──────────────────┐     OAuth (PKCE + DCR)      ┌──────────────────┐
│  Claude / MCP    │  ───────────────────────►   │  AWS Cognito     │
│  client          │                              │  (user pool)     │
└────────┬─────────┘                              └────────┬─────────┘
         │  Streamable HTTP /mcp                           │
         │  + bearer token                                 │
         ▼                                                 │
┌──────────────────┐     verify subscription tier          │
│  This server     │  ───────────────────────────────────► │
│  (FastAPI +      │                                       ▼
│   FastMCP)       │     proxy bearer token         ┌──────────────────┐
│                  │  ─────────────────────────►    │  api.            │
│  17 tools        │                                │  financial-      │
│  generated from  │                                │  reports.eu      │
│  OpenAPI schema  │                                │  (first-party)   │
└──────────────────┘                                └──────────────────┘

Ключевые архитектурные решения:

  • Инструменты генерируются автоматически, а не пишутся вручную. scripts/generate_mcp_tools.py читает схему OpenAPI — в CI и при сборке Docker используется зафиксированный в репозитории снимок, заданный параметром FR_PIN_SCHEMA=1, — и формирует src/financial_reports_mcp.py. По умолчанию используется тщательно отобранный набор из 17 инструментов; параметр MCP_FULL_SURFACE=1 включает полный набор. Обратите внимание: _PRUNED_EXCLUDE в генераторе — это список исключений, поэтому новая конечная точка upstream API попадёт в отобранный набор, если её явно не исключить в PR, обновляющем снимок схемы.

  • Токен Bearer передаётся прокси-сервером, а не хранится в сессии. Токен доступа пользователя Cognito пересылается в upstream API при каждом вызове. Данные диалогов и ответы API на сервере не кэшируются.

  • Проверка подписки выполняется в процессе. Кэш LRU с временем жизни 15 секунд хранит соответствия Cognito sub → уровня подписки, чтобы не обращаться к FR API при каждом вызове инструмента.

  • Прокси для ресурсов с тем же источником. /favicon.ico, /icon.png, /icon-{32,192,512}.png предоставляются с этого же источника — проксируются и кэшируются с CDN. Благодаря этому интерфейсы коннекторов и страница /consent отображаются без проблем, связанных с междоменными ограничениями CSP.

Соответствие спецификации MCP

Сервер соответствует спецификации MCP 2025-11-25:

  • ✅ Транспорт Streamable HTTP — POST /mcp с передачей заголовка MCP-Protocol-Version в ответе; неподдерживаемые версии приводят к ответу 400

  • ✅ OAuth 2.0 — динамическая регистрация клиентов по RFC 7591 и PKCE S256

  • ✅ Метаданные защищённого ресурса RFC 9728 — доступны по адресам /.well-known/oauth-protected-resource и /.well-known/oauth-protected-resource/mcp

  • ✅ Аннотации инструментов — у каждого инструмента есть title и readOnlyHint или destructiveHint

  • ✅ outputSchema — используется для шести инструментов со структурированным содержимым (companies_list, companies_retrieve, companies_financials_retrieve, filings_list, filings_retrieve, isins_list)

  • ✅ Проверка Origin — для неизвестных источников возвращается 403; для запросов без аутентификации — 401 с корректным заголовком WWW-Authenticate

  • ✅ Значки коннектора разных размеров — изображения PNG размером 32×32, 192×192 и 512×512 указываются в ответе initialize

CI проверяет всё перечисленное при создании каждого PR.

Каталог инструментов

Приведённый ниже список обновляется скриптом scripts/generate_mcp_tools.py при каждой сборке. Не редактируйте его вручную между маркерами.

Учётная запись

  • usage_retrieve — Получить сведения об использовании API и расходах

Компании

  • companies_financials_retrieve — Получить финансовую отчётность компании

  • companies_list — Получить список компаний

  • companies_next_annual_report_retrieve — Спрогнозировать дату следующего годового отчёта

  • companies_resolve_create — Найти компании по идентификаторам (пакетный запрос)

  • companies_retrieve — Получить сведения о компании

Категории отчётности

  • filing_categories_list — Получить список категорий отчётности

Типы отчётности

  • filing_types_list — Получить список типов отчётности

Документы

  • filings_list — Получить список документов

  • filings_markdown_retrieve — Получить документ в формате Markdown

  • filings_retrieve — Получить сведения о документе

ISIN

  • isins_list — Получить список ISIN

  • isins_retrieve — Получить сведения об ISIN

Примеры запросов

После подключения попробуйте следующие запросы:

  • «Найди последний 10-K Apple и кратко опиши изменения в факторах риска по сравнению с предыдущим годом».

  • «Получи полные сведения о компании ASML».

  • «Сравни чистый долг Iberdrola, Engie, Enel и RWE за последний финансовый год».

  • «Перечисли авиакомпании ЕС, подавшие годовые отчёты за последние 6 месяцев».

  • «Покажи документы Tesla о сделках инсайдеров за последние 30 дней».

  • «Сообщай мне, когда любая компания из моего списка наблюдения подаст 8-K».

  • «Какой LEI у Volkswagen AG?»

Самостоятельное размещение

Для самостоятельного размещения потребуется создать собственный пул пользователей AWS Cognito. Такой вариант в основном подходит для создания форка и адаптации сервера к другому upstream API. Для работы с FinancialFilings API рекомендуется использовать размещённый сервер mcp.financialfilings.com.

Подробная документация по самостоятельному размещению (Docker, настройка Cognito, переменные окружения, конфигурация CDN и значков): Документация по самостоятельному размещению.

Разработка

Быстрая настройка и запуск одной командой (venv → зависимости → проверка окружения → генерация → запуск):

cp .env.example .env   # fill in Cognito values first; see docs/SELF-HOSTING.md
make dev               # creates .venv, installs, validates env, regenerates, serves on :8000
# MCP endpoint: http://localhost:8000/mcp

Или выполните настройку по шагам:

# 1. Setup
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt -r requirements-test.txt

# 2. Configure
cp .env.example .env  # then fill in Cognito values; see docs/SELF-HOSTING.md

# 3. Generate the MCP module from the OpenAPI schema
python scripts/generate_mcp_tools.py

# 4. Run tests
pytest

# 5. Run locally
python -m uvicorn src.financial_reports_mcp:app --host 0.0.0.0 --port 8000
# MCP endpoint: http://localhost:8000/mcp

При каждом PR CI запускает полный набор модульных тестов и сквозной тест с Docker Compose и Redis. Подробнее см. в файле .github/workflows/ci.yml.

Локальная разработка с личным ключом API

Чтобы дорабатывать генератор, инструменты или запросы и проверять их на реальном сервере, не проходя OAuth-аутентификацию через Cognito после каждого перезапуска, можно использовать переменную окружения DEV_MODE_API_KEY, доступную только в режиме разработки. Если она задана, проверка JWT отключается для существующей конечной точки /mcp — в обоих путях subscription_required и _authorize_or_raise, — а ключ передаётся в API_BASE_URL в заголовке X-API-Key.

Это упрощение для сопровождающих, а не способ аутентификации для рабочего окружения. Модуль откажется загружаться, если MCP_BASE_URL содержит имя хоста рабочего сервера (mcp.financialfilings.com).

  • Добавьте личный ключ API FinancialFilings в .env:
DEV_MODE_API_KEY=fr_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
MCP_BASE_URL=http://localhost:8000
  • Перегенерируйте инструменты и запустите сервер. Переменные Cognito всё равно должны быть заданы: модуль OAuth-прокси загружается и при включённом обходе проверки.
make regen
python -m uvicorn src.financial_reports_mcp:app --host 0.0.0.0 --port 8000 --reload
  • Укажите локальный экземпляр в Claude Code:
claude mcp add --transport http financialfilings-local http://localhost:8000/mcp

Добавляйте эту настройку отдельно для каждого разработчика, а не в .mcp.json репозитория. В этом файле указан только рабочий сервер: каталоги, сканирующие репозиторий, например Cursor Directory, публикуют каждую запись из него как общедоступную установку.

Аутентификация без интерактивного входа для рабочего окружения по ключу API (отдельная конечная точка /mcp/apikey с передачей X-API-Key в каждом запросе) отслеживается в #28. Это отдельная функция, не связанная с упрощённым режимом разработки.

Типовые задачи

# Regenerate tools after the OpenAPI schema changes
python scripts/generate_mcp_tools.py

# Run only fast unit tests
pytest tests/test_*.py

# Run end-to-end tests with Redis (requires Docker)
make e2e

Оценка изменений

Сервер проходит тестирование с помощью financial-reports/mcp-evals (закрытый репозиторий). Сводные результаты для разных моделей — успешность выполнения задач, точность выбора инструментов, согласованность последовательности действий, количество токенов и ходов, задержка — хранятся там, а не в этом репозитории. Перед слиянием изменений в описания инструментов, запросы или генератор запускайте тестовый набор на рабочем сервере или локальном MCP в режиме разработки и сравнивайте результаты.

В этом репозитории находятся детерминированные тесты регистрации запросов в tests/eval/: они выполняются быстро, не требуют ключей API и запускаются при каждом PR. Описание процесса работы с несколькими репозиториями см. в файле tests/eval/README.md.

Безопасность

Этот сервер обрабатывает потоки OAuth и токены Bearer. Обнаружили уязвимость? Пожалуйста, не создавайте публичную задачу. О порядке ответственного раскрытия уязвимостей см. SECURITY.md.

Гарантии на стороне сервера:

  • Токены Bearer передаются прокси для каждого запроса и никогда не записываются в журналы и не сохраняются.

  • Используется только HTTPS: на границе сети HTTP перенаправляется на HTTPS.

  • К HTML-ответам применяется CSP (default-src 'none'): разрешены только ресурсы с того же источника.

  • Проверка источника отклоняет запросы с нераспознанных источников.

  • Все криптографические операции выполняются средствами стандартной библиотеки и AWS SDK; собственные криптографические алгоритмы не используются.

Участие в проекте

Мы приветствуем вклад в проект. В CONTRIBUTING.md описаны настройка среды разработки, порядок работы «повторная генерация → тестирование → PR», а также типы изменений, которые приветствуются (тесты, документация, улучшения генератора и вручную подготовленные описания инструментов в scripts/generate_mcp_tools.py), и те, которые будут отклонены (ручное редактирование src/financial_reports_mcp.py — этот файл генерируется автоматически и перезаписывается при каждой сборке).

Статус проекта

  • В эксплуатации: доступен по адресу https://mcp.financialfilings.com/mcp

  • Представлен в каталогах: каталог коннекторов Claude, каталог Cursor

  • Соответствие спецификации: MCP 2025-11-25

  • Проверено с: Claude.ai, Claude Code, Claude Desktop, Cursor, Windsurf. Примеры конфигурации также доступны для Codex, Kilo Code, opencode, Gemini CLI и Hermes (см. раздел «Подключение клиента»).

Лицензия

MIT — © FINANCIALREPORTS PTE. LTD.

Благодарности

Особая благодарность @itisaevalex за оригинальный MCP-сервер, созданный сообществом. Он послужил подтверждением концепции и вдохновил на создание этой официальной версии.

Проект создан на основе FastMCP, FastAPI и Model Context Protocol.