Finam MCP Server

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

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

Содержание

Предварительные требования
Быстрая установка
Получение API ключей
Возможности
Примеры запросов
Доступные инструменты
Конфигурация MCP клиентов
Важные особенности

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

Для настройки и запуска 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-клиента:

Claude Desktop - Локальная установка: используйте uvx → см. Настройка Claude Desktop
Cursor - Локальная установка: используйте uvx → см. Настройка Cursor
VS Code - Локальная установка: используйте uvx → см. Настройка VS Code

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

macOS Finder: Command + Shift + .
Linux файловые менеджеры: Ctrl + H
Windows File Explorer: Alt, V, H
Терминал (macOS/Linux): ls -a

Метод 1: Быстрая установка с uvx из PyPI

Примечание: Использование 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"
      }
    }
  }
}

Метод 2: Установка из исходников с помощью uv

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

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 ключей

Посетите Личный кабинет Finam Trade
Создайте демо-счёт (или используйте реальный счёт)
Сгенерируйте API ключи в разделе "API"

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

Возможности

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

Управление счётом
- Просмотр баланса, маржи и статуса счёта
- Информация о транзакциях и сделках
Работа с активами
- Получение информации о торговых инструментах
- Поиск инструментов по тикеру, бирже, типу
- Информация о биржах и расписании торгов
- Работа с опционами
Рыночные данные
- Получение исторических свечей с гибкими таймфреймами
- Котировки и последние сделки
- Стакан заявок
- Снапшоты инструментов
Управление ордерами
- Размещение рыночных, лимитных и стоп-ордеров
- Отмена ордеров (индивидуально или массово)
- Получение истории ордеров и активных заявок

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

Базовая торговля

Какой у меня текущий баланс счёта на Finam?
Покажи мои текущие позиции на счёте Finam.
Купи 10 акций Сбербанка по рыночной цене.
Продай 5 акций Газпрома с лимитной ценой 150 рублей.
Отмени все открытые ордера.
Покажи все мои активные заявки.

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

Покажи дневную историю цен Сбербанка за последние 5 торговых дней.
Какая была цена закрытия Газпрома вчера?
Получи последний бар для Лукойла.
Покажи текущую котировку для Яндекса.
Получи 5-минутные свечи для Сбербанка за последние 2 часа.

Информация об активах

Найди информацию об инструменте SBER@MOEX.
Покажи все доступные акции на Московской бирже.
Получи расписание торгов на сегодня.

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

Счёт и позиции

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 клиентам.

Настройка Claude Desktop

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

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

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

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

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

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

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

Настройка Cursor

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

Официальная документация по настройке 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

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

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

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

Откройте настройки VS Code (Ctrl/Cmd + ,)
Найдите "chat.mcp.enabled" и отметьте галочку для включения поддержки MCP
Найдите "github.copilot.chat.experimental.mcp" и отметьте галочку для использования файлов инструкций

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

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

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

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

Добавьте конфигурацию 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 в репозитории.

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

Это демонстрационный MCP-сервер для интеграции с Finam Trade API. Не является официальным решением от Finam.

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

Лицензия

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

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
src		src
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
fastmcp.json		fastmcp.json
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Finam MCP Server

Содержание

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

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

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

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

Возможности

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

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

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

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

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

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

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

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

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

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

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

TimeFrame для свечей

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

Технологии

Поддержка

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

Лицензия

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Finam MCP Server

Содержание

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

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

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

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

Возможности

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

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

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

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

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

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

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

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

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

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

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

TimeFrame для свечей

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

Технологии

Поддержка

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

Лицензия

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages