Korea Investment & Securities (KIS) REST API MCP (Model Context Protocol)

Dies ist ein Server, der die Korea Investment & Securities (KIS) REST API als MCP-Tools aufruft. Er bietet APIs für inländische/ausländische Aktienabfragen, Kontostandsabfragen und Aufträge, sowohl als katalogbasierte allgemeine Tools als auch als häufig verwendete Komfort-Tools.

Hauptfunktionen

• Katalogbasierter API-Aufruf

  • Bietet 166 REST-APIs in 8 Gruppen

  • Überprüfung von API-Gruppe/ID, Pfad, HTTP-Methode, TR_ID-Kandidaten und Anfrageparametern

  • Bereitstellung von koreanischen Labels, Eingabehilfen, Beispielwerten und wichtigen Codewerten pro Parameter

  • Vollständige Liste: API_CATALOG.md

• Inländische Aktien

  • Abfrage von aktuellem Preis, Kursverlauf (Zeitraum/täglich), Angebot/Nachfrage (Hoga), Branchenindex und Basisinformationen

  • Abfrage von Kontostand, Vermögensstatus, Kaufkraft und verkaufbarer Menge

  • Abfrage von Aufträgen/Auftragshistorie/stornierbaren Aufträgen

• Ausländische Aktien

  • Unterstützung für Marktcodes in den USA, Japan, China, Hongkong und Vietnam

  • Abfrage von aktuellem Preis, Kontostand, aktuellem Kontostand nach Ausführung, Margin pro Währung und Kaufkraft

  • Automatische Auswahl der TR_ID für Aufträge basierend auf Markt und Kauf-/Verkaufsrichtung

• Ausführung/Betrieb

  • Unterstützung für stdio, sse und streamable-http Transport

  • Konfiguration über .env oder Befehlszeilenargumente

  • Automatische Ergänzung von Kontonummer, Kontoproduktcode und Authentifizierungswerten

  • Token-Cache basierend auf App-Key und Kontotyp

  • Standardmäßige Ablehnung unbekannter Anfrageparameter

  • Standardmäßige Blockierung von Auftrags-/Änderungs-/Stornierungs-APIs

Related MCP server: kiwoom-mcp

Sicherheitsstandards

APIs, die den Kontostatus ändern, wie z. B. Aufträge/Änderungen/Stornierungen, sind standardmäßig blockiert.

KIS_ENABLE_TRADING=true

Die Statusänderungs-APIs werden nur ausgeführt, wenn die oben genannten Werte explizit festgelegt wurden. Wenn Sie nur Abfrage-APIs verwenden, konfigurieren Sie diese bitte nicht.

Anforderungen

• Python >= 3.13

• uv

Installation

Bitte folgen Sie INSTALL.md für die Installation. LLMs oder MCP-Clients sollten diese Datei ebenfalls zuerst lesen, wenn sie konfiguriert werden.

INSTALL.md enthält folgende Informationen:

• Installation von Abhängigkeiten basierend auf uv

• Erstellung von .env und Konfiguration von KIS_APP_KEY, KIS_APP_SECRET, KIS_CANO, KIS_ACNT_PRDT_CD

• Beispiele für die Registrierung in Codex CLI, Claude Code, Claude Desktop und allgemeinen MCP-Clients

• Konfiguration von KIS_MCP_TOOLSET=catalog zur Einsparung von Kontext

• Beispiele für call-kis-api zur Abfrage von Kontostand, Kaufkraft und aktuellem Preis

Schnelle lokale Vorbereitung:

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

Stellen Sie dann die folgenden Werte in .env ein. Weitere Informationen zu den Werten und Registrierungsbefehle pro Client finden Sie in 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"

Ausführung

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

Die Konfiguration kann auch über Befehlszeilenargumente erfolgen.

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

Auswahl des Transports:

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

Beispiel für die Registrierung eines MCP-Clients:

Unten finden Sie ein minimales Beispiel für einen allgemeinen MCP-Client. Verwenden Sie für Codex CLI, Claude Code und Claude Desktop die Befehle aus 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-Tool-Konfiguration

Katalog-Tools

list-kis-api-specs gibt zusammen mit den Labels, Beispielwerten und wichtigen Codewerten der erforderlichen Parameter zurück. get-kis-api-spec gibt label, guide, examples, values, default und auto_fill Informationen aller Parameter zurück, sodass das LLM die für den Aufruf erforderliche Eingabeform sofort überprüfen kann.

call-kis-api führt standardmäßig folgende Prozesse durch:

• Automatische Eingabe von Kontonummer/Kontoproduktcode basierend auf Umgebungsvariablen

• Ausstellung und Zwischenspeicherung von Authentifizierungstoken

• Konfiguration von GET/POST-Anfragen

• Automatische Auswahl der ausführbaren Auftrags-TR_ID aus mehreren TR_IDs

• Anwendung des Sicherheits-Gates für Statusänderungs-APIs

• Standardmäßige Ablehnung von Parametern, die nicht im Katalog enthalten sind

Komfort-Tools

Häufig verwendete Funktionen für inländische/ausländische Aktien werden auch als separate MCP-Tools bereitgestellt.

Auftragstools werden ebenfalls nicht ausgeführt, wenn KIS_ENABLE_TRADING=true nicht gesetzt ist.

Optimierung des Tool-Ladens

MCP-Clients laden Tool-Namen, Beschreibungen und Eingabeschemata in den Kontext, wenn sie eine Verbindung zum Server herstellen. Da die Offenlegung vieler Komfort-Tools den Kontextverbrauch zu Beginn des Gesprächs erhöht, kann bei Bedarf ein Leichtgewichtsmodus verwendet werden, der nur die 3 Katalog-Tools offenlegt.

KIS_MCP_TOOLSET=catalog uv run python server.py

Der catalog-Modus dient dazu, die Menge der geladenen MCP-Tool-Schemata zu reduzieren. Komfort-Tools werden ausgeblendet, aber die 166 APIs können weiterhin über call-kis-api aufgerufen werden. Benötigte APIs können mit list-kis-api-specs gefunden und benötigte detaillierte Parameter bei Bedarf mit get-kis-api-spec abgefragt werden.

Empfohlener Ablauf:

1. Suchen Sie die API mit list-kis-api-specs.

2. Überprüfen Sie erforderliche Parameter, Beispielwerte und Codewerte mit get-kis-api-spec.

3. Rufen Sie die tatsächliche API mit call-kis-api auf.

In der Konfiguration des MCP-Clients müssen lediglich Umgebungsvariablen hinzugefügt werden.

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

Wenn Sie häufig verwendete Komfort-Tools direkt in der Tool-Liste anzeigen möchten, verwenden Sie den Standardwert full.

call-kis-api Beispiele

Aktueller Preis inländischer Aktien:

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

Kontostand ausländischer Aktien:

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

Aktueller Kontostand ausländischer Aktien nach Ausführung:

{
  "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"
  }
}

Kaufkraft für ausländische Aktien:

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

Wichtige API-Gruppen

Die vollständigen API-IDs, Pfade, TR_IDs und Anleitungen zu erforderlichen Parametern sind in API_CATALOG.md zusammengefasst.

Umgebungsvariablen

Entwicklung/Validierung

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

Lizenz

MIT