lsopenapi

mcp-lsopenapi

AI에게 시세·차트·내 포트폴리오를 물어보세요.

Claude·ChatGPT·Copilot 같은 AI 비서에 LS증권 OpenAPI를 붙입니다. 시세·차트·기업정보·ETF·시장 스크리너·지수/업종/테마 컨텍스트, LS 실계좌 read-only 조회(v1.6), 그리고 내 페이퍼 포트폴리오·관심종목까지 — 평소 쓰던 대화창에서 자연어로 묻고 받습니다.

"오늘 코스피 어땠어? 강한 업종은?" "SK하이닉스 일봉 차트 보여주고 추세 봐줘" "내 LS 계좌 잔고 보여줘" — v1.6 "오늘 매매일지랑 수익률" — v1.6 "한투에서 삼성전자 64주 평단 21.5만에 샀어" "내 보유 중 2차전지 테마만 모아봐" "포트폴리오 백업해줘"

설정 한 번이면 됩니다. 종목 코드를 외울 필요도, HTS를 따로 띄울 필요도 없습니다.

대화창에 맞게 가볍게 답합니다. 차트·지수 시계열·보유종목처럼 커지기 쉬운 응답은 요약 우선 형태로 보내고, 필요한 경우에만 원본 데이터로 이어가도록 설계했습니다. 그래서 긴 차트 분석이나 스크리닝 대화도 불필요한 토큰을 덜 쓰고 이어갈 수 있습니다.

개발자용 기술 문서(환경 변수, 자격증명 정책, 도구 시그니처, 상세 스키마, SDK·빌드)는 영문 README에 있습니다.

---

이런 질문에 답합니다

도구 이름이 아니라 "어떤 질문에 답할 수 있는가" 로 묶었습니다.

시세 / 호가

"삼성전자 지금 얼마야?" · "카카오 호가창 보여줘" · "미장 테슬라 현재가" · "내 관심종목 10개 가격 한번에 비교"

국내 단일 종목 현재가와 10단계 호가, 해외주식 현재가/종목정보/10단계 호가, 또는 국내 최대 50종목 일괄 비교.

차트 / 기술적 분석

"SK하이닉스 일·주·월봉 같이 보여줘" · "NVDA 일봉에 이동평균선이랑 RSI" · "여기에 MA200도 추가해줘"

국내·해외 개별주식의 일·주·월·년·분·틱 차트, 이동평균·RSI·MACD·볼린저밴드 같은 기술 지표, 변곡점·MA 정렬·고점 대비 낙폭 같은 사전 계산된 분석. 국내·해외 모두 추가 지표나 기간 변경을 후속 대화에서 그대로 이어갈 수 있습니다.

종목 검색 / 기업 정보

"카카오 종목코드 뭐야?" · "테슬라 keysymbol 찾아줘" · "바이오 ETF 알려줘" · "삼성전자 PER이랑 분기별 매출 추이"

KOSPI/KOSDAQ 종목명 부분 검색, 미국/해외주식 마스터 검색, 일반주식/ETF 필터, PER/PBR/EPS·분기 재무·52주 가격 범위·상위 거래원·외국인 보유, SPAC·관리종목 플래그.

ETF 분석

"KODEX 200 NAV랑 괴리율 보여줘" · "TIGER 미국나스닥100 구성종목 비중 상위 10개"

ETF/ETN 전용 정보(NAV·추적오차율·괴리율·AUM·LP), 구성종목(PDF) 비중순 정렬과 상위 N개 제한.

시장 스크리닝

"오늘 상승률 상위 10개" · "거래대금 상위 + 시총 1조 이상" · "PER 낮은 종목 30개" · "오늘 외인 매수 상위"

등락률·시총·거래량·거래대금 상위, 거래 급증, 펀더멘털 랭킹(PER/PBR/ROE 등), 투자자 수급, 신고/신저가, 공매도 추이, 증권사 투자의견, 관리·매매정지 종목 — 가격·거래량 필터링과 함께.

저장된 신호 검색 (Q-Click) — v1.4

"골든크로스 신호 어떤 게 있어?" · "외국인 매수 streak 신호 돌려줘" · "거래대금 급증 ∩ 외인 매수 양쪽에 다 잡힌 종목"

LS가 큐레이션한 99개 신호 카탈로그(이평선 정배열·MA 돌파·공매도 추세·외국인 수급 streak 등)를 이름이나 키워드로 찾아 그대로 실행합니다. 두 개 이상을 AND(교집합) / OR(합집합) 으로 합쳐 한 번에 부를 수도 있어 — "거래대금 급증과 외국인 매수 둘 다 잡힌 종목" 처럼 HTS 한 화면에서는 표현할 수 없는 복합 조건도 한 번의 대화로 처리합니다.

지수 / 업종 / 테마 컨텍스트

"오늘 코스피" · "강한 업종은?" · "2차전지 테마 종목 비교" · "삼성전자가 속한 테마" · "나스닥·환율 어때?"

국내 지수 단건·시계열 조회, 해외 지수·환율·선물, 업종 등락률 랭킹, 업종/테마 안의 종목 일괄 시세, 종목별 테마 역조회. 키워드가 모호하면 후보를 보여주고 되묻습니다.

프로그램매매 / 기관 수급

"오늘 프로그램매매 어땠어?" · "프로그램이 순매수한 종목 상위" · "삼성전자 프로그램 수급 추이" · "삼성전자 기관이 매집 중인지 분석해줘"

시장 전체 프로그램매매(차익·비차익) 흐름을 분 단위·일 단위로, 종목별 프로그램 순매수 랭킹(시가총액 대비 비중으로 정규화), 개별 종목의 프로그램 수급 추이까지 — 모두 인라인 차트와 함께. 한 종목의 프로그램 발자국을 매집·분산·churn으로 판정하는 footprint 분석도.

LS 실계좌 read-only 조회 — v1.6

"내 LS 계좌 잔고" · "오늘 주문 체결됐어?" · "BEP 단가 알려줘" · "이번 달 수익률" · "오늘 매매일지" · "삼성전자 최대 몇 주 살 수 있어?"

LS appkey와 묶인 실계좌를 read-only로 조회합니다. 보유잔고·당일 주문/미체결·예수금/주문가능금액·기간 손익·일일 매매일지·주문이력·거래내역·신용한도·종목별 주문가능수량(증거금률 100% / 50% / 35% 별로). 매 호출마다 LS REST를 다시 쳐서 항상 최신 — 캐시 없음, 데몬 없음. 발주는 v1.7에서.

페이퍼 포트폴리오(accounts 테이블, 다중 브로커 수동 입력)와 LS 실계좌(ls_accounts 테이블, appkey 자동 발견)는 물리적으로 분리된 저장소라서, 페이퍼 계좌에 "LS증권" 라벨을 붙여도 실계좌 응답을 가리지 않습니다.

로컬 페이퍼 포트폴리오 / 관심종목 / 백업·복원

"한투에 삼성전자 10주 6.8만 샀어" · "5주 더 7.5만에 추가 매수" · "내 평가손익 보여줘" · "관심종목에 NAVER 추가" · "포트폴리오 백업해줘"

여러 증권사 계좌의 보유 종목·매수/매도 기록(가중평균 평단 자동 계산), 액면분할·무상증자 일괄 반영, 계좌별 + 통합 평가손익. 그룹별 관심종목과 관심 테마 추적, 단일 JSON 백업·복원. 내 보유 종목과 테마/업종을 교차한 필터("내 보유 중 2차전지 테마")도 한 번에. broker 라벨은 순수 표시용이라 "한투", "유안타증권", "LS증권 페이퍼" 등 자유롭게 붙일 수 있고, LS 실계좌와 절대 충돌하지 않습니다.

---

활용 사례

"HTS 한 화면으로는 짤 수 없는 흐름이 자연어 한 문장으로 처리되는 순간" 다섯 가지를 모았습니다:

• 차트 + 추세 설명을 한 번에 — "SK하이닉스 일봉 보여주고 추세 정렬 봐줘"
• 시장 스크리닝 → 후보 종목 분석까지 한 대화 안에서 — "거래대금 상위 종목을 기술적으로 분석해줘"
• 두 개의 저장 신호를 합쳐 — HTS 한 화면으로는 못 쓰는 조건 (v1.4) — "이평 골든크로스(5,20), 외인 3일연속 순매수, 양쪽 다 잡힌 종목만"
• 스크리닝 → 프로그램매매 footprint까지 (v1.1) — "방금 나온 4종목 중 NC소프트 프로그램 수급 흐름은?"
• 분할 매수 평단 머지 + 액면분할 일괄 반영 — "한투에 10주 21.5만에 샀고… 5주 더 24만에 추가 매수… 100원 액면분할 빠뜨렸네"

스크린샷·대화 흐름 전체는 활용 사례 모음에서.

---

설치 — 1분 컷

사전 준비. dnx는 .NET SDK 10 이상에 들어 있는 dotnet 도구 실행기입니다. 아직 없으면 .NET 다운로드에서 SDK를 먼저 설치하세요 (Windows/macOS/Linux 모두 지원). 터미널에서 dnx --help가 도움말을 출력하면 준비 완료입니다.

LS증권 OpenAPI 키 한 쌍(AppKey + AppSecretKey)이 필요합니다 — LS증권 → 고객센터 → 매매시스템 → API 에서 발급. 실투용과 모의투자용은 별도 키 페어입니다 (LS-API-QUIRKS §4.2d) — 한 모드를 쓰려면 그 모드 키를 LS_APPKEY / LS_APPSECRETKEY로 로드. LS_MARKET은 같은 키를 모드만 바꿔 쓰는 스위치가 아니라, 현재 주입된 키가 실전용인지 모의용인지 명시하는 런타임 모드입니다 — REST endpoint는 두 모드 동일, 라우팅은 키가 결정. 자세한 단계는 영문 README 참조.

Claude Desktop / Claude Code

claude_desktop_config.json (Claude Desktop) 또는 워크스페이스 루트의 .mcp.json (Claude Code)에 아래 한 덩어리를 붙여 넣고 호스트를 재시작합니다.

{
  "mcpServers": {
    "lsopenapi": {
      "command": "dnx",
      "args": ["RedoxNet.Mcp.LsOpenApi", "--yes"],
      "env": {
        "LS_APPKEY": "...",       // 실투 키이면 실계좌, 모의투자 키이면 모의계좌가 응답
        "LS_APPSECRETKEY": "...",
        "LS_MARKET": "real"       // ls_accounts(live) 라벨 + 토큰 cache 분리. 키와 일치시키세요 (모의투자 키면 "virtual"). 페이퍼 포트폴리오는 mode 무관.
      }
    }
  }
}

Cursor · Google Antigravity는 Claude Desktop과 같은 mcpServers JSON 스키마를 쓰므로 위 블록을 그대로 쓰고 파일 경로만 호스트별 위치로 바꾸시면 됩니다. Codex CLI (TOML) · VS Code (servers 키) · FieldCure AssistStudio (GUI 다이얼로그)는 형식이 달라 별도 예시 — 전체 호스트별 설정 예시와 환경 변수 목록은 영문 README에 있습니다.

차트 인라인 렌더링은 호스트별로 다릅니다. AssistStudio(v1.1 이상), Claude Desktop Chat, Claude Cowork, VS Code Chat 등 SEP-1865 호스트는 차트를 대화창에 인라인 그래프로 렌더링합니다(v1.5에서 PlotlyTemplate 핸드셰이크를 다듬어 광고만 하던 호스트도 실제 렌더하도록). Codex CLI / Claude Code CLI 같은 텍스트 전용 호스트에서는 차트 spec이 자동 제거되고 분석 요약만 전달됩니다 — 모델은 _meta.render_status("delivered" / "stripped_text_only") 신호를 읽어 "그렸다"고 거짓말하지 않습니다(v1.5). 어느 경우든 차트 스펙이 텍스트 컨텍스트를 오염시키지 않습니다(v1.2).

---

미국 / 해외주식 사용 시 추가 설정 (v1.3+)

v1.3부터 미장(Nasdaq / NYSE / AMEX) 종목의 시세·차트·종목 검색을 지원합니다. 국내주식만 쓰실 분은 이 섹션을 건너뛰셔도 됩니다. 미장 데이터를 받으려면 LS증권에서 약정 두 개를 추가로 신청해야 하지만 — API 키는 그대로 쓰면 됩니다. LS는 한 AppKey / AppSecretKey 페어에 약정 권한이 누적되는 모델입니다.

신청 순서

1. [HTS 2004] 해외주식 거래신청 — 계좌에 미국주식 거래 권한을 추가합니다. LS xingTrader에서 화면번호 2004 또는 해외시장 → 해외주식 → 거래신청. 동의 문서 4종(외화증권 거래설명서 / 해외주식 투자위험고지 / 해외주식 직접투자 신고 등 유의사항 / 개인신용정보 필수동의서)에 동의 후 신청. 종합매매계좌 그대로 사용 가능 — 새 계좌 개설은 불필요합니다.

2. [HTS 2007] 해외주식 실시간 시세신청 — 미국은 무료입니다. 화면번호 2007 또는 해외시장 → 해외주식 → 실시간 시세신청. 비전문가(일반 개인 고객) 필수정보 등록을 같이 처리해야 시세 권한이 부여됩니다. 신청하지 않으면 15분 지연시세가 기본값입니다. 장기간 LS HTS/MTS 미접속 또는 미국주식 거래가 없으면 LS 정책상 사전 통보 없이 자동 해지될 수 있으니 주기적으로 LS 클라이언트를 켜두는 게 안전합니다.

3. (만약 대차거래서비스 약정이 있으면) 먼저 해지 — LS 마이페이지 → 약정관리, 또는 1544-9911 콜로 해지. 대차거래 약정이 걸려있으면 다음 단계의 해외주식 OpenAPI 등록 화면이 차단됩니다.

4. [웹 마이페이지] 해외주식 OpenAPI 사용등록 — LS증권 → 마이페이지 → 매매시스템 → 사용등록/해지 → "해외주식 API" 라디오 선택 → 사용등록. 같은 AppKey / AppSecretKey 페어에 권한만 추가되므로 LS_APPKEY / LS_APPSECRETKEY 환경변수는 그대로입니다.

신청 직후부터 v1.3+ 도구가 동작합니다 — ls_search_overseas_stock, ls_get_overseas_quote, ls_get_overseas_chart, 그리고 미장 데이터셋에도 ls_add_indicator / ls_reframe_chart 후속 처리가 가능합니다.

유의사항

• AppKey 추가 발급 없음 — 국내·미장이 같은 키 페어를 공유합니다. 환경변수 변경 불필요.
• Non-Display 제한 — LS의 NYSE / Nasdaq 라이선스는 Display-only입니다. 결과를 사용자가 직접 보는 AI 비서 시나리오는 Display 범위로 해석되며, 자동매매 봇 / 외부 서비스로의 시세 재배포는 LS 약관 위반 소지가 있습니다.
• 수수료 — 미국주식 매매 수수료는 OPEN API 매체 0.25%. (시세 데이터 사용료는 별도 부과 없음.) v1.3 도구는 read-only라 매매수수료 발생 없음 — 향후 주문 기능이 추가될 경우의 비용 정보입니다.
• 타임존 — quote의 timestamp는 한국 시간(timestamp_tz: "Asia/Seoul"), 차트의 일/분봉은 미국 동부시간 기준(bar_timezone: "America/New_York")입니다. NVDA "5/22 일봉" = NYSE 5/22 거래 세션 = 한국 시간으로 5/22 22:30 ~ 5/23 05:00 구간.

---

데이터와 보안

• 내 페이퍼 포트폴리오·관심종목은 로컬 디스크에만 저장됩니다 (%LOCALAPPDATA%\RedoxNet\LsOpenApi\portfolio.db). 외부 송신은 없습니다. v1.6부터 LS 실계좌의 AcntNo + 지점명/계좌명 라벨도 같은 파일의 별도 ls_accounts 테이블에 자동 발견 시점에 저장됩니다 (실시간 잔고/주문 자체는 캐시하지 않고 매 호출마다 LS REST를 새로 침).
• 브로커·시장 연동은 read-only입니다 — v1.6은 시장 데이터 조회 + LS 실계좌의 잔고·보유·주문이력·BEP·주문가능수량 등 inquiry까지만 수행하고, 실주문(매매·정정·취소)은 지원하지 않습니다 (v1.7에 paper-default + preview-gate로 도입 예정). 페이퍼 포트폴리오는 사용자가 직접 입력해 로컬 DB/JSON에 기록 — ls_holding(매수/매도/보유 기록), ls_account(action="upsert")(계좌 등록), ls_portfolio_io(JSON 백업/복구) 같은 로컬 write가 있고, 이건 외부 송신 없이 본인 PC에만 머뭅니다.
• 자격증명(API 키)은 환경변수로만 전달받습니다. 채팅·도구 인자·MCP 엘리시테이션 등 모델이 관찰할 수 있는 경로로는 절대 받지 않습니다 — 의도된 보안 설계이며, 상세 정책은 영문 README에 있습니다.

---

면책 조항

이 프로젝트는 비공식 third-party MCP 서버입니다. LS증권(LS Securities Co., Ltd.)과 공식적인 제휴·후원·승인 관계가 없으며, "LS증권" 및 관련 상표는 해당 권리자의 소유입니다.

본 도구는 정보 제공 목적의 시세·차트 데이터 조회용입니다. 투자 자문이나 매매 권유가 아니며, 주식 거래에는 원금 손실을 포함한 위험이 따릅니다. 모든 투자 결정과 그에 따른 손익은 전적으로 사용자 본인의 책임입니다.

API 사용 시 LS증권 OpenAPI 이용 안내를 참조하고, 사이트에 표시되는 정식 이용약관을 확인 후 준수하시기 바랍니다. 현재 범위는 국내주식 중심의 read-only 시장 데이터 + 해외주식 시세·차트 조회(해외 지수·환율·선물 스냅샷 포함) + LS 실계좌 read-only 조회(v1.6 — 보유·잔고·주문이력·일일손익·기간손익·BEP·주문가능수량·신용한도) + 로컬 페이퍼 포트폴리오 노트(다중 브로커, watchlist, 테마, JSON 백업/복구)입니다. v1.7에서 주문 발주 가 추가 예정입니다. 실시간 시세(WebSocket) 는 현재 고려 대상이 아닙니다.

---

관련 자료

• 개발자용 기술 문서 — README.en.md
• 릴리스 노트 — Mcp · Core
• 사례 분석 — 좁은 구간에서도 한 번에 끝내는 토큰 효율 분석
• License — MIT