Skip to main content
Glama
FinamWeb

Finam MCP Server

by FinamWeb
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Remote

Finam MCP Server

Python FastMCP License

MCP (Model Context Protocol) сервер для интеграции с торговой платформой Finam через Trade API.

Комплексный MCP-сервер для Finam Trade API, позволяющий осуществлять торговые операции через AI-ассистентов, таких как Claude Desktop и Cursor, используя естественный язык.

Содержание

Предварительные требования

Для настройки и запуска Finam MCP Server вам потребуется:

  • Терминал (macOS/Linux) | Command Prompt или PowerShell (Windows)

  • Python 3.12+ (Проверьте официальное руководство по установке и подтвердите версию командой: python3 --version в терминале)

  • uv (Установите используя официальное руководство) Совет: uv можно установить через менеджер пакетов (например, Homebrew) или напрямую используя curl | sh

  • Finam Trade API ключи (бесплатный демо-счёт доступен)

  • MCP клиент (Claude Desktop, Cursor, VS Code и т.д.)

Примечание: Использование MCP-сервера требует установки и настройки как самого MCP-сервера, так и MCP-клиента.

Быстрая установка

Выберите подходящий способ установки для вашего MCP-клиента:

Примечание: Как показать скрытые файлы

  • macOS Finder: Command + Shift + .

  • Linux файловые менеджеры: Ctrl + H

  • Windows File Explorer: Alt, V, H

  • Терминал (macOS/Linux): ls -a

Примечание: Использование MCP-сервера требует установки и настройки как самого MCP-сервера, так и MCP-клиента.

# Установка из PyPI
uvx finam-mcp-server@latest

Примечание: Если у вас ещё нет uv, установите его сначала и перезапустите терминал, чтобы uv/uvx стали доступны. См. официальное руководство: https://docs.astral.sh/uv/getting-started/installation/

Затем добавьте в конфигурацию вашего MCP-клиента:

Расположение конфигурационных файлов:

  • Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) или %APPDATA%\Claude\claude_desktop_config.json (Windows)

  • Cursor: ~/.cursor/mcp.json (Mac/Linux) или %USERPROFILE%\.cursor\mcp.json (Windows)

{
  "mcpServers": {
    "finam": {
      "command": "uvx",
      "args": ["finam-mcp-server@latest"],
      "env": {
        "FINAM_API_KEY": "ваш-api-ключ",
        "FINAM_ACCOUNT_ID": "ваш-account-id"
      }
    }
  }
}

Клонируйте репозиторий и перейдите в директорию:

git clone https://github.com/Alexander-Panov/finam-mcp.git
cd finam-mcp

Установите зависимости:

# С использованием uv (рекомендуется)
uv sync

# Или pip
pip install -e .

После установки/клонирования и активации виртуального окружения структура директорий должна выглядеть так:

finam-mcp/                  ← Рабочая директория (корень проекта)
├── src/                    ← Исходный код пакета
│   ├── __init__.py
│   ├── cli.py              ← Интерфейс командной строки
│   ├── config.py           ← Управление конфигурацией
│   ├── main.py             ← Главный MCP-сервер
│   ├── middleware.py       ← Middleware для аутентификации
│   ├── servers/            ← Специализированные MCP-серверы
│   │   ├── account.py      ← Операции со счётом
│   │   ├── assets.py       ← Работа с инструментами
│   │   ├── market_data.py  ← Рыночные данные
│   │   └── order.py        ← Торговые операции
│   └── tradeapi/           ← Обёртки над Finam Trade API
│       ├── finam.py        ← Основной клиент
│       └── order/          ← Модели и клиент для ордеров
├── tests/                  ← Тесты
├── .venv/                  ← Виртуальное окружение
├── fastmcp.json            ← Конфигурация FastMCP
├── pyproject.toml          ← Конфигурация пакета
├── README.md
└── LICENSE

Получение API ключей

  1. Посетите Личный кабинет Finam Trade

  2. Создайте демо-счёт (или используйте реальный счёт)

  3. Сгенерируйте API ключи в разделе "Токены"

Полезные ссылки

Возможности

Сервер предоставляет доступ к следующим функциям Finam Trade API:

  • Управление счётом

    • Просмотр баланса, маржи и статуса счёта

    • Информация о транзакциях и сделках

  • Работа с активами

    • Получение информации о торговых инструментах

    • Поиск инструментов по тикеру, бирже, типу

    • Информация о биржах и расписании торгов

    • Работа с опционами

  • Рыночные данные

    • Получение исторических свечей с гибкими таймфреймами

    • Котировки и последние сделки

    • Стакан заявок

    • Снапшоты инструментов

  • Управление ордерами

    • Размещение рыночных, лимитных и стоп-ордеров

    • Отмена ордеров (индивидуально или массово)

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

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

  1. Какой у меня текущий баланс счёта на Finam?

  2. Покажи мои текущие позиции на счёте Finam.

  3. Купи 10 акций Сбербанка по рыночной цене.

  4. Продай 5 акций Газпрома с лимитной ценой 150 рублей.

  5. Отмени все открытые ордера.

  6. Покажи все мои активные заявки.

  1. Покажи дневную историю цен Сбербанка за последние 5 торговых дней.

  2. Какая была цена закрытия Газпрома вчера?

  3. Получи последний бар для Лукойла.

  4. Покажи текущую котировку для Яндекса.

  5. Получи 5-минутные свечи для Сбербанка за последние 2 часа.

  1. Найди информацию об инструменте SBER@MOEX.

  2. Покажи все доступные акции на Московской бирже.

  3. Получи расписание торгов на сегодня.

Доступные инструменты

  • get_account_info() - Просмотр баланса и статуса счёта

  • get_transactions() - История транзакций

  • get_trades() - История сделок

  • get_assets() - Список всех торговых инструментов с фильтрацией

  • get_asset_params() - Параметры конкретного инструмента

  • get_exchanges() - Список бирж

  • get_exchange_info() - Информация о конкретной бирже

  • get_option_boards() - Информация о площадках опционов

  • get_trade_schedule() - Расписание торговых сессий

  • get_candles() - Исторические свечи с различными таймфреймами

  • get_quotes() - Текущие котировки

  • get_order_book() - Стакан заявок

  • get_last_trades() - Последние сделки

  • get_orders() - Получение всех или отфильтрованных ордеров

  • place_order() - Размещение ордера (market, limit, stop)

  • cancel_order() - Отмена конкретного ордера

  • cancel_all_orders() - Отмена всех открытых ордеров

Конфигурация MCP клиентов

Ниже вы найдёте пошаговые руководства для подключения Finam MCP сервера к различным MCP клиентам.

Примечание: Предполагается, что все предварительные требования установлены.

Метод: uvx (Рекомендуется)

Простой и современный подход:

  1. Откройте Claude Desktop → Settings → Developer → Edit Config

  2. Добавьте эту конфигурацию:

    {
  "mcpServers": {
    "finam": {
      "type": "stdio",
      "command": "uvx",
      "args": ["finam-mcp-server@latest"],
      "env": {
        "FINAM_API_KEY": "ваш-api-ключ",
        "FINAM_ACCOUNT_ID": "ваш-account-id"
      }
    }
  }
}

  3. Перезапустите Claude Desktop и начинайте торговать!

Примечание: Предполагается, что все предварительные требования установлены.

Официальная документация по настройке MCP в Cursor: https://docs.cursor.com/context/mcp

Использование JSON конфигурации

Откройте и отредактируйте ~/.cursor/mcp.json (macOS/Linux) или %USERPROFILE%\.cursor\mcp.json (Windows):

{
  "mcpServers": {
    "finam": {
      "type": "stdio",
      "command": "uvx",
      "args": ["finam-mcp-server@latest"],
      "env": {
        "FINAM_API_KEY": "ваш-api-ключ",
        "FINAM_ACCOUNT_ID": "ваш-account-id"
      }
    }
  }
}

VS Code поддерживает MCP серверы через режим агента GitHub Copilot. Официальная документация: https://code.visualstudio.com/docs/copilot/chat/mcp-servers

Примечание: Предполагается, что все предварительные требования установлены.

1. Включите поддержку MCP в VS Code

  1. Откройте настройки VS Code (Ctrl/Cmd + ,)

  2. Найдите "chat.mcp.enabled" и отметьте галочку для включения поддержки MCP

  3. Найдите "github.copilot.chat.experimental.mcp" и отметьте галочку для использования файлов инструкций

2. Настройте MCP сервер (рекомендуется uvx)

Рекомендация: Используйте конфигурацию для конкретного workspace (.vscode/mcp.json) вместо общей конфигурации пользователя.

Для настроек workspace:

  1. Создайте .vscode/mcp.json в корне вашего проекта

  2. Добавьте конфигурацию Finam MCP сервера вручную в файл mcp.json:

    {
  "mcp": {
    "servers": {
      "finam": {
        "type": "stdio",
        "command": "uvx",
        "args": ["finam-mcp-server@latest"],
        "env": {
          "FINAM_API_KEY": "ваш-api-ключ",
          "FINAM_ACCOUNT_ID": "ваш-account-id"
        }
      }
    }
  }
}

Тестирование с MCP Inspector

MCP Inspector позволяет интерактивно тестировать все инструменты сервера:

npx @modelcontextprotocol/inspector

Подключитесь к серверу, используя адрес: http://localhost:3000/mcp и добавив заголовки с ключом Finam API и Account ID.

Важные особенности

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

Все инструменты указываются в формате ТИКЕР@MIC:

  • SBER@MOEX - Сбербанк на Московской бирже

  • GAZP@MOEX - Газпром на Московской бирже

  • По умолчанию используются биржи: MOEX, SPBE

Формат времени

API требует даты и время в формате ISO 8601:

  • 2024-01-15T10:30:00Z

  • 2024-01-15T10:30:00+03:00

TimeFrame для свечей

Доступные таймфреймы из finam_trade_api.instruments.TimeFrame:

  • M1, M5, M15, M30 - минуты

  • H1, H4 - часы

  • D1 - день

  • W1 - неделя

Использование FastMCP конфигурации

Проект поддерживает декларативную конфигурацию через fastmcp.json:

# Запуск с автоматическим обнаружением fastmcp.json
fastmcp run

# Или явное указание файла
fastmcp run fastmcp.json

# Для разработки с Inspector UI
fastmcp dev

Технологии

  • Python 3.12+

  • FastMCP - фреймворк для создания MCP-серверов

  • FinamTradeApiPy - Python-обёртка для Finam Trade API

Поддержка

По вопросам и предложениям создавайте Issue в репозитории.

Отказ от ответственности

Не является инвестиционной рекомендацией. Все торговые операции осуществляются на ваш страх и риск. Автор не несёт ответственности за возможные убытки при использовании данного сервера. Тщательно проверяйте все действия, предлагаемые AI-ассистентом, особенно для сложных торговых операций.

Лицензия

MIT License - см. файл LICENSE для деталей.