# MOEX MCP Server

MCP-сервер для доступа к данным Московской Биржи через [ISS API](https://iss.moex.com/iss/reference/).

Позволяет AI-ассистентам (Claude Code, Claude Desktop и др.) получать котировки, историю торгов, свечи, информацию о бумагах, индексах, валютных курсах и многое другое.

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

- Node.js 18+

## Установка

```bash
git clone <repo-url> moex-mcp
cd moex-mcp
npm install
npm run build
```

## Подключение

### Claude Code

```bash
claude mcp add moex node /path/to/moex-mcp/dist/index.js
```

### Claude Desktop / ручная настройка

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

```json
{
  "mcpServers": {
    "moex": {
      "command": "node",
      "args": ["/path/to/moex-mcp/dist/index.js"]
    }
  }
}
```

## Инструменты (20 шт.)

### Поиск и информация о бумагах

| Инструмент | Описание |
| --- | --- |
| `search_securities` | Поиск бумаг по тикеру, названию или ISIN |
| `get_security_info` | Спецификация бумаги: ISIN, номинал, даты, площадки |
| `get_security_indices` | Индексы, в которые входит бумага |

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

| Инструмент | Описание |
| --- | --- |
| `get_market_data` | Текущие данные: цена, объём, bid/ask, изменение |
| `get_orderbook` | Стакан заявок |
| `get_recent_trades` | Последние сделки |
| `get_candles` | OHLCV-свечи (1, 10, 60 мин или дневные) |

### Исторические данные

| Инструмент | Описание |
| --- | --- |
| `get_history` | Итоги торгов за период |
| `get_history_date_range` | Доступный диапазон дат для бумаги |
| `get_historical_candles` | Исторические свечи за период |

### Справочники

| Инструмент | Описание |
| --- | --- |
| `list_engines` | Торговые системы (stock, currency, futures и др.) |
| `list_markets` | Рынки торговой системы |
| `list_boards` | Режимы торгов |

### Аналитика и статистика

| Инструмент | Описание |
| --- | --- |
| `get_index_analytics` | Аналитика индексов, состав и веса (IMOEX, RTSI) |
| `get_currency_rates` | Валютные курсы: фиксинг MOEX, ЦБ РФ, индикативные |
| `get_market_turnovers` | Обороты по рынкам |
| `get_bond_yield_curve` | Кривая бескупонной доходности (ZCYC) |
| `get_futures_open_positions` | Открытые позиции по фьючерсам |

### Корпоративные действия

| Инструмент | Описание |
| --- | --- |
| `get_dividends` | История дивидендных выплат |
| `get_coupons` | График купонных выплат по облигациям |

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

После подключения сервера можно обращаться к данным биржи на естественном языке:

- «Найди акции Сбербанка»
- «Покажи текущую цену GAZP»
- «Дай историю торгов SBER за январь 2025»
- «Какие дивиденды платил Лукойл?»
- «Покажи состав индекса IMOEX»
- «Курс доллара по фиксингу ЦБ»
- «Свечи YNDX за последний месяц с интервалом 1 день»

## Параметры по умолчанию

Большинство инструментов используют значения по умолчанию для удобства:

- `engine` = `"stock"` (фондовый рынок)
- `market` = `"shares"` (акции)

Для работы с другими рынками (облигации, валюта, фьючерсы) укажите параметры явно.

## Аутентификация

Сервер работает без аутентификации. В этом режиме рыночные данные приходят с 15-минутной задержкой. Индексы всегда доступны в реальном времени.

## Архитектура

Vertical Slice + Hexagonal (Ports & Adapters):

```
src/
├── index.ts                    # Composition root
├── server.ts                   # Регистрация MCP-инструментов
├── shared/
│   ├── ports/                  # Интерфейсы (порты)
│   ├── adapters/               # Реализации (адаптеры)
│   ├── pagination.ts           # Авто-пагинация
│   └── formatter.ts            # Форматирование для LLM
└── features/                   # 20 вертикальных слайсов
    └── <tool-name>/
        ├── schema.ts           # Zod-схема параметров
        ├── query.ts            # Бизнес-логика запроса
        └── handler.ts          # MCP-обработчик
```

## Лицензия

MIT