MCP (Model Context Protocol) для REST API Korea Investment & Securities

Это сервер, который вызывает REST API Korea Investment & Securities (KIS) в качестве инструментов MCP. Он предоставляет API для запроса отечественных/иностранных акций, проверки счетов и заказов через универсальные инструменты на основе каталога, а также часто используемые инструменты удобства.

Основные функции

• Вызовы на основе каталога API

  • Предоставление 166 REST API в 8 группах

  • Проверка группы/ID API, пути, HTTP-метода, кандидатов TR_ID и параметров запроса

  • Предоставление корейских меток для каждого параметра, руководств по вводу, примеров значений и основных кодов

  • Полный список: API_CATALOG.md

• Отечественные акции

  • Запрос текущей цены, котировок за период/день, заявок, индексов отраслей и базовой информации

  • Запрос баланса, состояния активов инвестиционного счета, суммы, доступной для покупки, и количества, доступного для продажи

  • Запрос заказов/истории заказов/заказов, доступных для исправления/отмены

• Иностранные акции

  • Поддержка кодов рынков США, Японии, Китая, Гонконга и Вьетнама

  • Запрос текущей цены, баланса, текущего баланса на основе исполнения, маржи по валютам и суммы, доступной для покупки

  • Автоматический выбор TR_ID заказа в зависимости от рынка и направления покупки/продажи

• Запуск/Эксплуатация

  • Поддержка транспорта stdio, sse, streamable-http

  • Настройка на основе .env или аргументов командной строки

  • Автоматическое дополнение номера счета, кода продукта счета и значений аутентификации

  • Кэширование токенов на основе ключа приложения и типа счета

  • Отклонение неизвестных параметров запроса по умолчанию

  • Блокировка API заказов/исправлений/отмен по умолчанию

Related MCP server: kiwoom-mcp

Безопасные значения по умолчанию

API, изменяющие состояние счета, такие как заказы/исправления/отмены, по умолчанию заблокированы.

KIS_ENABLE_TRADING=true

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

Требования

• Python >= 3.13

• uv

Установка

Установка выполняется в соответствии с INSTALL.md. LLM или MCP-клиенты также должны сначала прочитать этот файл при настройке.

INSTALL.md содержит следующую информацию:

• Установка зависимостей на основе uv

• Создание .env и настройка KIS_APP_KEY, KIS_APP_SECRET, KIS_CANO, KIS_ACNT_PRDT_CD

• Примеры регистрации для Codex CLI, Claude Code, Claude Desktop и обычных MCP-клиентов

• Настройка KIS_MCP_TOOLSET=catalog для экономии контекста

• Примеры call-kis-api для запроса баланса, суммы для покупки и текущей цены

Быстрая локальная подготовка:

pip install uv
uv sync
cp .env.example .env
chmod 600 .env

Затем установите следующие значения в .env. Подробное описание значений и команды регистрации для каждого клиента см. в INSTALL.md.

KIS_APP_KEY="발급받은 앱키"
KIS_APP_SECRET="발급받은 시크릿키"
KIS_ACCOUNT_TYPE="REAL"   # REAL 또는 VIRTUAL
KIS_CANO="계좌번호 앞 8자리"
KIS_ACNT_PRDT_CD="01"
KIS_MCP_TOOLSET="catalog"

Запуск

# stdio, 로컬 MCP 클라이언트 권장
uv run python server.py

Настройки также можно задать через аргументы командной строки.

uv run python server.py \
  --app-key "앱키" \
  --app-secret "시크릿키" \
  --account-type "REAL" \
  --cano "계좌번호" \
  --acnt-prdt-cd "01"

Выбор транспорта:

MCP_TYPE=stdio uv run python server.py
MCP_TYPE=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 MCP_PATH=/mcp uv run python server.py
MCP_TYPE=sse MCP_HOST=127.0.0.1 MCP_PORT=8000 MCP_PATH=/sse uv run python server.py

Пример регистрации MCP-клиента:

Ниже приведен минимальный пример для обычного MCP-клиента. Для команд Codex CLI, Claude Code и Claude Desktop используйте INSTALL.md.

{
  "mcpServers": {
    "kis-mcp-server": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "cwd": "<project-root>",
      "env": {
        "KIS_MCP_TOOLSET": "catalog",
        "KIS_MCP_LOG_LEVEL": "WARNING"
      }
    }
  }
}

Конфигурация инструментов MCP

Инструменты каталога

list-kis-api-specs возвращает метки, примеры значений и основные коды обязательных параметров. get-kis-api-spec возвращает информацию label, guide, examples, values, default, auto_fill для всех параметров, чтобы LLM могла сразу увидеть формат ввода, необходимый для вызова.

call-kis-api выполняет следующие общие действия:

• Автоматический ввод номера счета/кода продукта счета на основе переменных окружения

• Выпуск и кэширование токенов аутентификации

• Конфигурация GET/POST запросов

• Автоматический выбор TR_ID заказа из нескольких вариантов

• Применение шлюза безопасности для API изменения состояния

• Отклонение параметров, отсутствующих в каталоге, по умолчанию

Инструменты удобства

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

Инструменты заказа также не будут работать без KIS_ENABLE_TRADING=true.

Оптимизация загрузки инструментов

При подключении к серверу MCP-клиент загружает имена инструментов, описания и схемы ввода в контекст. Чем больше инструментов удобства отображается, тем больше потребление контекста в начале диалога, поэтому при необходимости можно использовать облегченный режим, отображающий только 3 инструмента каталога.

KIS_MCP_TOOLSET=catalog uv run python server.py

Режим catalog предназначен для уменьшения объема загрузки схемы инструментов MCP. Хотя инструменты удобства скрыты, 166 API по-прежнему можно вызывать через call-kis-api. Необходимые API можно найти с помощью list-kis-api-specs, а подробные параметры — запрашивать через get-kis-api-spec по мере необходимости.

Рекомендуемый рабочий процесс:

1. Поиск API с помощью list-kis-api-specs.

2. Проверка обязательных параметров, примеров значений и кодов с помощью get-kis-api-spec.

3. Вызов фактического API с помощью call-kis-api.

В настройках MCP-клиента достаточно добавить переменные окружения.

{
  "env": {
    "KIS_MCP_TOOLSET": "catalog"
  }
}

Если вы хотите, чтобы часто используемые инструменты удобства отображались непосредственно в списке инструментов, используйте значение по умолчанию full.

Примеры call-kis-api

Текущая цена отечественных акций:

{
  "group": "domestic_stock",
  "api_type": "inquire_price",
  "params": {
    "fid_cond_mrkt_div_code": "J",
    "fid_input_iscd": "005930"
  }
}

Баланс иностранных акций:

{
  "group": "overseas_stock",
  "api_type": "inquire_balance",
  "params": {
    "ovrs_excg_cd": "NASD",
    "tr_crcy_cd": "USD"
  }
}

Текущий баланс иностранных акций на основе исполнения:

{
  "group": "overseas_stock",
  "api_type": "inquire_present_balance",
  "params": {
    "wcrc_frcr_dvsn_cd": "01",
    "natn_cd": "000",
    "tr_mket_cd": "00",
    "inqr_dvsn_cd": "00"
  }
}

Сумма, доступная для покупки иностранных акций:

{
  "group": "overseas_stock",
  "api_type": "inquire_psamount",
  "params": {
    "ovrs_excg_cd": "NASD",
    "ovrs_ord_unpr": "1",
    "item_cd": "QQQ"
  }
}

Основные группы API

Полный список ID API, путей, TR_ID и руководств по обязательным параметрам приведен в API_CATALOG.md.

Переменные окружения

Разработка/Проверка

uv run python -m compileall main.py server.py example.py tests
uv run python -m unittest discover -v
git diff --check

Лицензия

MIT