# Finam MCP Server

MCP сервер для работы с Finam API - предоставляет 18 инструментов для торговли, получения рыночных данных и управления аккаунтом.

## 🔧 Установка

### Через MCP конфигурацию (рекомендуется)

Добавьте в ваш `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "finam": {
      "command": "uvx",
      "args": [
        "git+ssh://git@github.com/mdmeldon/finam-mcp.git"
      ],
      "env": {
        "FINAM_API_TOKEN": "ваш_api_токен_finam",
        "FINAM_ACCOUNT_ID": "ваш_account_id"
      },
      "description": "MCP server for Finam API"
    }
  }
}
```

**Важно:** Замените `ваш_api_токен_finam` на ваш реальный API токен от Finam, и `ваш_account_id` на ID вашего торгового счета.

### Локальная разработка

```bash
# Клонируйте репозиторий
git clone git@github.com:mdmeldon/finam-mcp.git
cd finam-mcp

# Установите зависимости через uv
uv sync

# Создайте .env файл с вашими учетными данными
cat > .env << EOF
FINAM_API_TOKEN=ваш_api_токен_finam
FINAM_ACCOUNT_ID=ваш_account_id
EOF

# Запустите сервер
uv run finam_mcp
```

**Альтернатива:** Можно передать переменные окружения напрямую:

```bash
FINAM_API_TOKEN=ваш_токен FINAM_ACCOUNT_ID=ваш_id uv run finam_mcp
```

## 📋 Доступные инструменты (18 tools)

### 🔐 Аккаунты и портфель
- `get_account` - Информация по аккаунту
- `trades` - История сделок за период
- `transactions` - Список транзакций

### 📊 Справочные данные
- `assets` - Список доступных инструментов
- `clock` - Время сервера
- `exchanges` - Список бирж
- `get_asset` - Информация по инструменту
- `get_asset_params` - Торговые параметры инструмента
- `options_chain` - Цепочка опционов
- `schedule` - Расписание торгов

### 📝 Заявки
- `cancel_order` - Отменить заявку
- `get_order` - Получить заявку по ID
- `get_orders` - Список заявок аккаунта
- `place_order` - Выставить новую заявку

### 📈 Рыночные данные
- `bars` - Исторические бары
- `last_quote` - Последняя котировка
- `latest_trades` - Последние сделки
- `order_book` - Текущий стакан заявок

## 🚀 Использование

После установки в Cursor, все инструменты будут доступны через MCP интерфейс. 

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

Сервер использует переменные окружения для аутентификации:

- **`FINAM_API_TOKEN`** (обязательно) - API токен для доступа к Finam API
- **`FINAM_ACCOUNT_ID`** (обязательно) - ID торгового счета

Эти параметры передаются один раз при настройке MCP сервера и автоматически используются во всех инструментах.

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

После настройки, инструменты можно вызывать без указания токена и account_id:

```python
# Получить информацию о счете
get_account()

# Получить историю сделок
trades(start_time="2024-01-01T00:00:00Z", end_time="2024-01-31T23:59:59Z")

# Получить список активов
assets()

# Получить последнюю котировку
last_quote(symbol="SBER")
```

**Важно:** API токен используется только для получения короткоживущего JWT (~15 минут), после чего все запросы выполняются с использованием JWT. Клиент автоматически обновляет JWT при необходимости.

## 🛠️ Требования

- Python >= 3.12
- uv (для управления зависимостями)

## 📝 Лицензия

MIT


