Skip to main content
Glama
market-mcp

market-mcp

by konstantinmk

market-mcp

Локальный MCP-сервер, через который Claude получает данные Московской биржи (MOEX ISS) и брокерского счёта в Т-Инвестициях (T-Invest API). Сервер только читает данные: методов выставления заявок в коде нет.

Установка

Нужны Python 3.12+ и uv (pip install uv или winget install astral-sh.uv).

git clone <repo> C:\projects\market-mcp
cd C:\projects\market-mcp
uv sync
copy .env.example .env   # при необходимости впишите TINVEST_TOKEN
uv run pytest            # юнит-тесты на фикстурах, без сети

Без токена работают котировки, свечи, скринер, индексы и купоны через MOEX ISS с задержкой 15 минут. С токеном котировки идут в реальном времени, а ещё появляются стакан, дивиденды и (при ENABLE_PORTFOLIO=true) данные счёта.

Токен T-Invest: в приложении Т-Инвестиций откройте Настройки → Токены T-Invest API и выпустите токен «Только чтение». Для разработки можно включить TINVEST_SANDBOX=true.

Related MCP server: moex-mcp

Подключение к Claude Desktop

Добавьте блок в %APPDATA%\Claude\claude_desktop_config.json и перезапустите Claude:

{
  "mcpServers": {
    "market": {
      "command": "uv",
      "args": ["--directory", "C:\\projects\\market-mcp", "run", "market-mcp"],
      "env": { "TINVEST_TOKEN": "t.…", "ENABLE_PORTFOLIO": "true" }
    }
  }
}

Если uv не находится, укажите полный путь к uv.exe (where uv). Токен можно не писать в конфиг: сервер читает .env из папки проекта.

Для Claude Code: claude mcp add market -- uv --directory C:\projects\market-mcp run market-mcp.

Инструменты

Инструмент

Параметры

Источник

Что возвращает

find_instrument

query, kind?, limit=10

оба

Кандидаты: ticker, board, figi, secid, название, тип

get_quote

ticker, board?

T-Invest → ISS

Цена, изменение за день, объём, статус торгов

get_candles

ticker, interval, date_from?, date_to?, board?, cursor?

ISS / T-Invest

OHLCV, не больше 1000 за вызов

get_orderbook

ticker, depth=10, board?

T-Invest

Стакан bids/asks

screen_market

board, filters?, sort, order, limit=50, cursor?

ISS

Бумаги режима торгов, не больше 500 строк

get_index

index_id=IMOEX, date_from?, date_to?

ISS

Текущее значение и история

get_payouts

ticker, date_from?, date_to?

T-Invest (купоны — и ISS)

Дивиденды или купоны с датами отсечки

get_portfolio

account_id?

T-Invest

Стоимость, доли классов, позиции, P&L

get_operations

date_from?, date_to?, account_id?, types?, cursor?

T-Invest

Сделки, комиссии, выплаты

get_portfolio и get_operations не регистрируются, пока ENABLE_PORTFOLIO не равен true.

В ТЗ параметры периода названы from/to. В сервере это date_from/date_to: from — зарезервированное слово Python, а MCP SDK не умеет переименовывать аргументы.

Контракт ответа

{
  "data": { "ticker": "SBER", "board": "TQBR", "price": "279.26", "change_day_pct": "-0.24",
            "volume": 10617169, "currency": "RUB", "trading_status": "normal_trading" },
  "source": "moex",
  "as_of": "2026-09-17T10:06:23Z",
  "stale": true,
  "delay_minutes": 15
}
  • Цены и суммы передаются строками, чтобы не терять точность Decimal. Все метки времени в UTC. Даты YYYY-MM-DD на входе считаются торговыми днями по Москве.

  • stale: true означает, что данные не в реальном времени (ISS). Вне торгов price — цена закрытия, а в ответе есть notice.code = "market_closed".

  • Цена облигации в price — рубли за бумагу с НКД. Цена в процентах от номинала лежит в price_pct_of_face.

  • Если ответ разбит на страницы, в нём есть next_cursor: передайте его в cursor следующего вызова.

  • Ошибка приходит как {"error": {"code", "message", "retriable"}}. Коды: instrument_not_found, ambiguous_instrument (+candidates), auth_failed, token_required, rate_limited (+retry_after_seconds), upstream_unavailable, portfolio_disabled, invalid_argument, account_not_found.

Настройки

Переменная

Назначение

По умолчанию

TINVEST_TOKEN

Токен «только чтение»

—

TINVEST_SANDBOX

Работа через песочницу

false

ENABLE_PORTFOLIO

Регистрировать инструменты счёта

false

MOEX_BASE_URL

Базовый URL ISS

https://iss.moex.com/iss

CACHE_PATH

Файл SQLite-кэша

~/.market-mcp/cache.db

LOG_LEVEL

Уровень логов

INFO

HTTP_TIMEOUT

Таймаут запроса, с

10

Как устроено

src/market_mcp/
├─ server.py          регистрация инструментов и запуск по stdio
├─ tools/             market.py, portfolio.py — схемы и описания инструментов
├─ app.py             сборка зависимостей; ошибки превращаются в {"error": …}
├─ domain.py          выбор источника, нормализация, кэш, постраничность
├─ providers/         moex.py (ISS), tinvest.py (REST-фасад, только методы чтения)
├─ mapping.py         справочник ticker ↔ figi ↔ instrument_uid ↔ SECID в SQLite, обновление раз в сутки
├─ cache.py           SQLite + TTL, ключ sha256(tool + аргументы)
├─ ratelimit.py       token bucket (ISS 5 rps) и учёт квот T-Invest по x-ratelimit-*
├─ http.py            общий httpx-клиент, 3 повтора (0.5 → 2 → 8 с) на сетевые ошибки, 429 и 5xx
├─ money.py           Quotation / MoneyValue ↔ Decimal
├─ models.py          Instrument, Quote, Candle, Position, коды ошибок, конверт ответа
└─ logging_setup.py   JSON-логи только в stderr, токен вырезается
  • TTL кэша: справочник — 24 ч, свечи закрытых дней — бессрочно, свечи текущего дня — 60 с, котировки — 15 с, скринер — 5 мин. Портфель, операции и стакан не кэшируются, данные счёта в SQLite не пишутся.

  • Безопасность: токен передаётся только в заголовке Authorization, в логи, ошибки и ответы не попадает. Номера счетов маскируются до ****1234, и тот же формат принимается в account_id.

  • TLS: у T-Invest сертификат выдан российским удостоверяющим центром, поэтому httpx проверяет его по системному хранилищу сертификатов через truststore. Если T-Invest отвечает ошибкой TLS, установите в Windows корневой сертификат Минцифры.

Разработка

uv run ruff check src tests
uv run mypy                       # strict
uv run pytest                     # фикстуры + respx, без сети
uv run pytest -m live             # реальные API, запускать вручную
uv run python scripts/smoke.py    # живой прогон всех рыночных инструментов через stdio
npx @modelcontextprotocol/inspector uv run market-mcp

В VS Code конфигурации из .vscode/launch.json запускают MCP Inspector, smoke-тест и pytest.

Главное правило: никаких print(). stdout занят протоколом MCP, а все логи пишутся через logging в stderr.

Available Tools

7 tools
find_instrumentA
Read-onlyIdempotent

Найти биржевой инструмент по тикеру, названию или ISIN (Мосбиржа и справочник Т-Инвестиций).

    Используй, когда пользователь называет компанию словами («Сбер», «Яндекс», «ОФЗ 26238»)
    или когда другой инструмент вернул instrument_not_found / ambiguous_instrument.
    Возвращает кандидатов с ticker, board, figi, secid, названием, типом и валютой.
    

Inputs: query (required), kind, limit. Returns: object

get_candlesA
Read-onlyIdempotent

Исторические свечи OHLCV от 1 минуты до месяца — для динамики цены, доходности за период, графиков.

    Дневные, недельные и месячные свечи берутся с MOEX ISS без ограничения глубины;
    внутридневные — из T-Invest, если есть токен. По умолчанию: день — последний год, внутри дня — сутки.
    За один вызов не больше 1000 свечей: при next_cursor повтори запрос с cursor.
    Время: дата YYYY-MM-DD для day/week/month, иначе UTC ISO 8601.
    

Inputs: ticker (required), board, cursor, date_to, +2 more. Returns: object

get_indexA
Read-onlyIdempotent

Значение биржевого индекса Мосбиржи сейчас и, если задан период, дневная история закрытий.

Используй для сравнения доходности бумаги или портфеля с рынком (IMOEX, MCFTR — полной доходности).

Inputs: cursor, date_to, index_id, date_from. Returns: object

get_orderbookA
Read-onlyIdempotent

Биржевой стакан: лучшие заявки на покупку (bids) и продажу (asks) с количеством в лотах.

    Нужен для оценки ликвидности и спреда. Требует токен T-Invest.
    

Inputs: ticker (required), board, depth. Returns: object

get_payoutsA
Read-onlyIdempotent

Дивиденды по акции или купоны по облигации: суммы на одну бумагу, даты отсечки и выплаты.

    По умолчанию — от года назад до года вперёд, включая объявленные будущие выплаты.
    Дивиденды требуют токен T-Invest; купоны доступны и через MOEX ISS.
    

Inputs: ticker (required), board, date_to, date_from. Returns: object

get_quoteA
Read-onlyIdempotent

Текущая котировка бумаги: цена, изменение за день в %, объём, статус торгов.

    Источник — T-Invest в реальном времени (если задан токен), иначе MOEX ISS с задержкой 15 минут
    (stale: true). Вне торгов price — цена закрытия, в ответе notice.code = market_closed.
    Для облигаций price — рублёвая цена одной бумаги с НКД, price_pct_of_face — цена в % от номинала.
    

Inputs: ticker (required), board. Returns: object

screen_marketA
Read-onlyIdempotent

Скринер всех бумаг режима торгов Мосбиржи с фильтрами и сортировкой.

    Для вопросов «самые ликвидные акции», «кто сильнее всех упал сегодня», «ОФЗ с доходностью выше 15%».
    Строки: secid, name, price, change_pct, volume, value_rub, capitalization; для облигаций ещё
    yield_pct, duration_days, maturity. Данные ISS с задержкой 15 минут. Не больше 500 строк за вызов.
    

Inputs: sort, board, limit, order, +2 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct purpose: instrument lookup, current quote, historical candles, order book, screening, index data, and payouts. There is no meaningful overlap; even get_quote and get_candles are clearly separated by real-time vs historical scope.

    Naming Consistency5/5

    All tool names follow a snake_case verb_noun pattern: find_instrument, get_quote, get_candles, get_orderbook, screen_market, get_index, get_payouts. The verbs (find/get/screen) are distinct and consistent with each tool's action, and the overall pattern is uniform.

    Tool Count5/5

    Seven tools is well within the ideal range for a market-data server. Each tool covers a necessary data type without redundancy, making the set feel complete yet focused.

    Completeness5/5

    The surface covers the core market-data lifecycle: searching instruments, current quotes, historical candles, order book depth, market screening, index comparison, and dividend/coupon payouts. No obvious missing operations for the stated domain.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables read-only access to Interactive Brokers data including contracts, market data, news, fundamentals, and portfolio/account information for LLM workflows and autonomous agents.
      19
      BSD 3-Clause
    • A
      license
      B
      quality
      D
      maintenance
      Provides access to Moscow Exchange data including quotes, trade history, candles, securities info, indices, and currency rates. Enables AI assistants to query financial market data through natural language.
      20
      21 npm
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables Claude or any MCP host to access live market data—quotes, history, technical indicators, and NYSE status—and answer natural-language questions about stocks.
      4
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to query a T-Bank (Tinkoff) investment account in read-only mode, covering accounts, portfolio and positions, operation history, instrument lookup, market data such as candles and order books, plus technical indicators, fundamentals, analyst consensus and dividend or bond coupon analytics through one-line tool calls. No tool can place trades, withdraw funds or change account settings, and a read-only API token is recommended.
      39
      50 PyPI
      3
      MIT