KIS REST API MCP Server

Instructions

Implementation Reference

• server.py:460-511 (handler)

  The complete handler implementation for the 'inquery-order-detail' MCP tool, including the @mcp.tool decorator (registration), function signature (schema), and the core logic that calls the Korea Investment & Securities API for order details using httpx.
  @mcp.tool( name="inquery-order-detail", description="Get order detail from Korea Investment & Securities", ) async def inquery_order_detail(order_no: str, order_date: str): """ Get order detail from Korea Investment & Securities Args: order_no: Order number order_date: Order date (YYYYMMDD) Returns: Dictionary containing order detail information """ async with httpx.AsyncClient() as client: token = await get_access_token(client) # Prepare request data request_data = { "CANO": os.environ["KIS_CANO"], # 계좌번호 "ACNT_PRDT_CD": "01", # 계좌상품코드 "INQR_DVSN": "00", # 조회구분 "PDNO": "", # 종목코드 "ORD_STRT_DT": order_date, # 주문시작일자 "ORD_END_DT": order_date, # 주문종료일자 "SLL_BUY_DVSN_CD": "00", # 매도매수구분 "CCLD_DVSN": "00", # 체결구분 "ORD_GNO_BRNO": "", # 주문채번지점번호 "ODNO": order_no, # 주문번호 "INQR_DVSN_3": "00", # 조회구분3 "INQR_DVSN_1": "", # 조회구분1 "CTX_AREA_FK100": "", # 연속조회검색조건100 "CTX_AREA_NK100": "", # 연속조회키100 } response = await client.get( f"{TrIdManager.get_domain('order_detail')}{ORDER_DETAIL_PATH}", headers={ "content-type": CONTENT_TYPE, "authorization": f"{AUTH_TYPE} {token}", "appkey": os.environ["KIS_APP_KEY"], "appsecret": os.environ["KIS_APP_SECRET"], "tr_id": TrIdManager.get_tr_id("order_detail") }, params=request_data ) if response.status_code != 200: raise Exception(f"Failed to get order detail: {response.text}") return response.json()
• server.py:68-165 (helper)

  TrIdManager class providing transaction IDs and domains for API calls, specifically 'order_detail' TR_ID used in the tool.
  class TrIdManager: """Transaction ID manager for Korea Investment & Securities API""" # 실전계좌용 TR_ID REAL = { # 국내주식 "balance": "TTTC8434R", # 잔고조회 "price": "FHKST01010100", # 현재가조회 "buy": "TTTC0802U", # 주식매수 "sell": "TTTC0801U", # 주식매도 "order_list": "TTTC8001R", # 일별주문체결조회 "order_detail": "TTTC8036R", # 주문체결내역조회 "stock_info": "FHKST01010400", # 일별주가조회 "stock_history": "FHKST03010200", # 주식일별주가조회 "stock_ask": "FHKST01010200", # 주식호가조회 # 해외주식 "us_buy": "TTTT1002U", # 미국 매수 주문 "us_sell": "TTTT1006U", # 미국 매도 주문 "jp_buy": "TTTS0308U", # 일본 매수 주문 "jp_sell": "TTTS0307U", # 일본 매도 주문 "sh_buy": "TTTS0202U", # 상해 매수 주문 "sh_sell": "TTTS1005U", # 상해 매도 주문 "hk_buy": "TTTS1002U", # 홍콩 매수 주문 "hk_sell": "TTTS1001U", # 홍콩 매도 주문 "sz_buy": "TTTS0305U", # 심천 매수 주문 "sz_sell": "TTTS0304U", # 심천 매도 주문 "vn_buy": "TTTS0311U", # 베트남 매수 주문 "vn_sell": "TTTS0310U", # 베트남 매도 주문 } # 모의계좌용 TR_ID VIRTUAL = { # 국내주식 "balance": "VTTC8434R", # 잔고조회 "price": "FHKST01010100", # 현재가조회 "buy": "VTTC0802U", # 주식매수 "sell": "VTTC0801U", # 주식매도 "order_list": "VTTC8001R", # 일별주문체결조회 "order_detail": "VTTC8036R", # 주문체결내역조회 "stock_info": "FHKST01010400", # 일별주가조회 "stock_history": "FHKST03010200", # 주식일별주가조회 "stock_ask": "FHKST01010200", # 주식호가조회 # 해외주식 "us_buy": "VTTT1002U", # 미국 매수 주문 "us_sell": "VTTT1001U", # 미국 매도 주문 "jp_buy": "VTTS0308U", # 일본 매수 주문 "jp_sell": "VTTS0307U", # 일본 매도 주문 "sh_buy": "VTTS0202U", # 상해 매수 주문 "sh_sell": "VTTS1005U", # 상해 매도 주문 "hk_buy": "VTTS1002U", # 홍콩 매수 주문 "hk_sell": "VTTS1001U", # 홍콩 매도 주문 "sz_buy": "VTTS0305U", # 심천 매수 주문 "sz_sell": "VTTS0304U", # 심천 매도 주문 "vn_buy": "VTTS0311U", # 베트남 매수 주문 "vn_sell": "VTTS0310U", # 베트남 매도 주문 } @classmethod def get_tr_id(cls, operation: str) -> str: """ Get transaction ID for the given operation Args: operation: Operation type ('balance', 'price', 'buy', 'sell', etc.) Returns: str: Transaction ID for the operation """ is_real_account = os.environ.get("KIS_ACCOUNT_TYPE", "REAL").upper() == "REAL" tr_id_map = cls.REAL if is_real_account else cls.VIRTUAL return tr_id_map.get(operation) @classmethod def get_domain(cls, operation: str) -> str: """ Get domain for the given operation Args: operation: Operation type ('balance', 'price', 'buy', 'sell', etc.) Returns: str: Domain URL for the operation """ is_real_account = os.environ.get("KIS_ACCOUNT_TYPE", "REAL").upper() == "REAL" # 잔고조회는 실전/모의 계좌별로 다른 도메인 사용 if operation == "balance": return DOMAIN if is_real_account else VIRTUAL_DOMAIN # 조회 API는 실전/모의 동일한 도메인 사용 if operation in ["price", "stock_info", "stock_history", "stock_ask"]: return DOMAIN # 거래 API는 계좌 타입에 따라 다른 도메인 사용 return DOMAIN if is_real_account else VIRTUAL_DOMAIN
• server.py:40-40 (helper)

  API endpoint path for order detail inquiry used by the tool.
  ORDER_DETAIL_PATH = "/uapi/domestic-stock/v1/trading/inquire-ccnl" # 주문체결내역조회