npm package: @ru-financial-tools/moex-mcp
Description: MCP сервер для MOEX ISS (Model Context Protocol server)
Latest version: 1.0.1

# MOEX MCP сервер

![Node](https://img.shields.io/badge/node-20%2B-green)
![License](https://img.shields.io/badge/license-MIT-blue)

Лёгкий MCP‑сервер для работы с ISS (MOEX) через Model Context Protocol. Поддерживает 10 инструментов, покрывающих ключевые разделы ISS API.

### Основные возможности
- `iss_reference`: engines, markets, boards, securities_by_board, security
- `iss_securities_search`: поиск бумаг (`/iss/securities.json`)
- `iss_marketdata`: котировки по площадке/бумаге (`iss.only=marketdata`)
- `iss_orderbook`: стакан заявок по бумаге
- `iss_trades`: лента сделок (recent | by_date)
- `iss_candles`: свечи (intraday/history by interval)
- `iss_history`: история торгов (daily | daily_by_board)
- `iss_indices`: индексы (list | index | history | members)
- `iss_turnovers`: обороты (root | board)
- `iss_reference_dicts`: сводный reference root и разделы

## Установка
Минимальные требования: Node.js 20+

Вариант 1 (запуск без установки, через npx):
```bash
npx -y --package=@ru-financial-tools/moex-mcp moex-mcp
```

Вариант 2 (локальная установка):
```bash
npm i -D @ru-financial-tools/moex-mcp
```

## Интеграция с Cursor (MCP)
Добавьте сервер в `.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "moex-mcp": {
      "command": "npx",
      "args": ["-y", "--package=@ru-financial-tools/moex-mcp", "moex-mcp"],
      "env": {
        "LOG_LEVEL": "info",
        "MOEX_ISS_BASE_URL": "https://iss.moex.com/iss"
      }
    }
  }
}
```
Перезапустите Cursor и выберите сервер `moex-mcp`.

## Конфигурация окружения
- `MOEX_ISS_BASE_URL` — базовый URL ISS (по умолчанию `https://iss.moex.com/iss`).
- `LOG_LEVEL` — уровень логирования: `debug` | `info`.
- Кэш (Keyv + SQLite, включён по умолчанию):
  - `MOEX_CACHE_DISABLED=1` — выключить кэш
  - `MOEX_CACHE_PATH=".cache/custom.sqlite"` — задать пользовательский путь

## Быстрый старт: примеры инструментов
- `iss_reference`:
  - Engines: `{ operation: "engines" }`
  - Markets: `{ operation: "markets", engine: "stock" }`
  - Boards: `{ operation: "boards", engine: "stock", market: "shares" }`
- `iss_securities_search`: `{ q: "GAZP" }`
- `iss_marketdata`:
  - Board quotes: `{ operation: "board_quotes", engine: "stock", market: "shares", board: "TQBR" }`
  - Security quotes: `{ operation: "security_quotes", engine: "stock", market: "shares", secid: "GAZP" }`
- `iss_trades`:
  - Recent: `{ operation: "recent", engine: "stock", market: "shares", board: "TQBR", secid: "GAZP" }`
  - By date: `{ operation: "by_date", engine: "stock", market: "shares", date: "2025-01-15" }`
- `iss_candles`: `{ engine: "stock", market: "shares", secid: "GAZP", interval: 60 }`
- `iss_history`:
  - Daily by board: `{ operation: "daily_by_board", engine: "stock", market: "shares", board: "TQBR", secid: "GAZP" }`
  - Daily: `{ operation: "daily", engine: "stock", market: "shares", secid: "GAZP" }`
- `iss_indices`:
  - List: `{ operation: "list" }`
  - Index: `{ operation: "index", secid: "IMOEX" }`
  - History: `{ operation: "history", secid: "IMOEX" }`
  - Members: `{ operation: "members", secid: "IMOEX" }`
- `iss_turnovers`:
  - Root: `{ operation: "root" }`
  - Board: `{ operation: "board", engine: "stock", market: "shares", board: "TQBR" }`
- `iss_reference_dicts`: `{}` или `{ section: "securities" }`

### Дополнительные промпты
- `moex_quickstart`, `moex_resources_help`, `moex_find_board` — доступны в Prompts.

## Отказоустойчивость клиента
- Повторы: до 5 попыток, экспоненциальная задержка 150мс → 2с с джиттером
- Кэш: Keyv (SQLite), отключаемый
- Ошибки: `HttpError` (408/429/5xx — ретраи), сетевые — ретраи

## Лицензия
MIT