{
  "markdown": "<p align=\"right\">\n  <strong>한글</strong> · <a href=\"README.en.md\">English</a>\n</p>\n\n# mcp-lsopenapi\n\n[![NuGet Mcp](https://img.shields.io/nuget/v/RedoxNet.Mcp.LsOpenApi?label=Mcp)](https://www.nuget.org/packages/RedoxNet.Mcp.LsOpenApi/)\n[![NuGet Core](https://img.shields.io/nuget/v/RedoxNet.LsOpenApi.Core?label=Core)](https://www.nuget.org/packages/RedoxNet.LsOpenApi.Core/)\n[![CI](https://github.com/redoxnet/mcp-lsopenapi/actions/workflows/ci.yml/badge.svg)](https://github.com/redoxnet/mcp-lsopenapi/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n## AI에게 시세·차트·내 포트폴리오를 물어보세요.\n\nClaude·ChatGPT·Copilot 같은 AI 비서에 **LS증권 OpenAPI**를 붙입니다. 시세·차트·기업정보·ETF·시장 스크리너·지수/업종/테마 컨텍스트, LS 실계좌 read-only 조회(v1.6), 그리고 내 페이퍼 포트폴리오·관심종목까지 — 평소 쓰던 대화창에서 자연어로 묻고 받습니다.\n\n> *\"오늘 코스피 어땠어? 강한 업종은?\"*\n> *\"SK하이닉스 일봉 차트 보여주고 추세 봐줘\"*\n> *\"내 LS 계좌 잔고 보여줘\"* — v1.6\n> *\"오늘 매매일지랑 수익률\"* — v1.6\n> *\"한투에서 삼성전자 64주 평단 21.5만에 샀어\"*\n> *\"내 보유 중 2차전지 테마만 모아봐\"*\n> *\"포트폴리오 백업해줘\"*\n\n설정 한 번이면 됩니다. 종목 코드를 외울 필요도, HTS를 따로 띄울 필요도 없습니다.\n\n대화창에 맞게 가볍게 답합니다. 차트·지수 시계열·보유종목처럼 커지기 쉬운 응답은 요약 우선 형태로 보내고, 필요한 경우에만 원본 데이터로 이어가도록 설계했습니다. 그래서 긴 차트 분석이나 스크리닝 대화도 불필요한 토큰을 덜 쓰고 이어갈 수 있습니다.\n\n> 개발자용 기술 문서(환경 변수, 자격증명 정책, 도구 시그니처, 상세 스키마, SDK·빌드)는 [영문 README](README.en.md)에 있습니다.\n\n---\n\n## 이런 질문에 답합니다\n\n도구 이름이 아니라 *\"어떤 질문에 답할 수 있는가\"* 로 묶었습니다.\n\n### 시세 / 호가\n> *\"삼성전자 지금 얼마야?\"* · *\"카카오 호가창 보여줘\"* · *\"미장 테슬라 현재가\"* · *\"내 관심종목 10개 가격 한번에 비교\"*\n\n국내 단일 종목 현재가와 10단계 호가, 해외주식 현재가/종목정보/10단계 호가, 또는 국내 최대 50종목 일괄 비교.\n\n### 차트 / 기술적 분석\n> *\"SK하이닉스 일·주·월봉 같이 보여줘\"* · *\"NVDA 일봉에 이동평균선이랑 RSI\"* · *\"여기에 MA200도 추가해줘\"*\n\n국내·해외 개별주식의 일·주·월·년·분·틱 차트, 이동평균·RSI·MACD·볼린저밴드 같은 기술 지표, 변곡점·MA 정렬·고점 대비 낙폭 같은 사전 계산된 분석. 국내·해외 모두 추가 지표나 기간 변경을 후속 대화에서 그대로 이어갈 수 있습니다.\n\n### 종목 검색 / 기업 정보\n> *\"카카오 종목코드 뭐야?\"* · *\"테슬라 keysymbol 찾아줘\"* · *\"바이오 ETF 알려줘\"* · *\"삼성전자 PER이랑 분기별 매출 추이\"*\n\nKOSPI/KOSDAQ 종목명 부분 검색, 미국/해외주식 마스터 검색, 일반주식/ETF 필터, PER/PBR/EPS·분기 재무·52주 가격 범위·상위 거래원·외국인 보유, SPAC·관리종목 플래그.\n\n### ETF 분석\n> *\"KODEX 200 NAV랑 괴리율 보여줘\"* · *\"TIGER 미국나스닥100 구성종목 비중 상위 10개\"*\n\nETF/ETN 전용 정보(NAV·추적오차율·괴리율·AUM·LP), 구성종목(PDF) 비중순 정렬과 상위 N개 제한.\n\n### 시장 스크리닝\n> *\"오늘 상승률 상위 10개\"* · *\"거래대금 상위 + 시총 1조 이상\"* · *\"PER 낮은 종목 30개\"* · *\"오늘 외인 매수 상위\"*\n\n등락률·시총·거래량·거래대금 상위, 거래 급증, 펀더멘털 랭킹(PER/PBR/ROE 등), 투자자 수급, 신고/신저가, 공매도 추이, 증권사 투자의견, 관리·매매정지 종목 — 가격·거래량 필터링과 함께.\n\n### 저장된 신호 검색 (Q-Click) — v1.4\n> *\"골든크로스 신호 어떤 게 있어?\"* · *\"외국인 매수 streak 신호 돌려줘\"* · *\"거래대금 급증 ∩ 외인 매수 양쪽에 다 잡힌 종목\"*\n\nLS가 큐레이션한 99개 신호 카탈로그(이평선 정배열·MA 돌파·공매도 추세·외국인 수급 streak 등)를 이름이나 키워드로 찾아 그대로 실행합니다. 두 개 이상을 **AND(교집합) / OR(합집합)** 으로 합쳐 한 번에 부를 수도 있어 — *\"거래대금 급증과 외국인 매수 둘 다 잡힌 종목\"* 처럼 HTS 한 화면에서는 표현할 수 없는 복합 조건도 한 번의 대화로 처리합니다.\n\n### 지수 / 업종 / 테마 컨텍스트\n> *\"오늘 코스피\"* · *\"강한 업종은?\"* · *\"2차전지 테마 종목 비교\"* · *\"삼성전자가 속한 테마\"* · *\"나스닥·환율 어때?\"*\n\n국내 지수 단건·시계열 조회, 해외 지수·환율·선물, 업종 등락률 랭킹, 업종/테마 안의 종목 일괄 시세, 종목별 테마 역조회. 키워드가 모호하면 후보를 보여주고 되묻습니다.\n\n### 프로그램매매 / 기관 수급\n> *\"오늘 프로그램매매 어땠어?\"* · *\"프로그램이 순매수한 종목 상위\"* · *\"삼성전자 프로그램 수급 추이\"* · *\"삼성전자 기관이 매집 중인지 분석해줘\"*\n\n시장 전체 프로그램매매(차익·비차익) 흐름을 분 단위·일 단위로, 종목별 프로그램 순매수 랭킹(시가총액 대비 비중으로 정규화), 개별 종목의 프로그램 수급 추이까지 — 모두 인라인 차트와 함께. 한 종목의 프로그램 발자국을 매집·분산·churn으로 판정하는 footprint 분석도.\n\n### LS 실계좌 read-only 조회 — v1.6\n> *\"내 LS 계좌 잔고\"* · *\"오늘 주문 체결됐어?\"* · *\"BEP 단가 알려줘\"* · *\"이번 달 수익률\"* · *\"오늘 매매일지\"* · *\"삼성전자 최대 몇 주 살 수 있어?\"*\n\nLS appkey와 묶인 실계좌를 read-only로 조회합니다. 보유잔고·당일 주문/미체결·예수금/주문가능금액·기간 손익·일일 매매일지·주문이력·거래내역·신용한도·종목별 주문가능수량(증거금률 100% / 50% / 35% 별로). 매 호출마다 LS REST를 다시 쳐서 **항상 최신** — 캐시 없음, 데몬 없음. 발주는 v1.7에서.\n\n페이퍼 포트폴리오(`accounts` 테이블, 다중 브로커 수동 입력)와 LS 실계좌(`ls_accounts` 테이블, appkey 자동 발견)는 **물리적으로 분리된 저장소**라서, 페이퍼 계좌에 \"LS증권\" 라벨을 붙여도 실계좌 응답을 가리지 않습니다.\n\n### 로컬 페이퍼 포트폴리오 / 관심종목 / 백업·복원\n> *\"한투에 삼성전자 10주 6.8만 샀어\"* · *\"5주 더 7.5만에 추가 매수\"* · *\"내 평가손익 보여줘\"* · *\"관심종목에 NAVER 추가\"* · *\"포트폴리오 백업해줘\"*\n\n여러 증권사 계좌의 보유 종목·매수/매도 기록(가중평균 평단 자동 계산), 액면분할·무상증자 일괄 반영, 계좌별 + 통합 평가손익. 그룹별 관심종목과 관심 테마 추적, 단일 JSON 백업·복원. 내 보유 종목과 테마/업종을 교차한 필터(*\"내 보유 중 2차전지 테마\"*)도 한 번에. **broker 라벨은 순수 표시용**이라 \"한투\", \"유안타증권\", \"LS증권 페이퍼\" 등 자유롭게 붙일 수 있고, LS 실계좌와 절대 충돌하지 않습니다.\n\n---\n\n## 활용 사례\n\n*\"HTS 한 화면으로는 짤 수 없는 흐름이 자연어 한 문장으로 처리되는 순간\"* 다섯 가지를 모았습니다:\n\n- **차트 + 추세 설명을 한 번에** — *\"SK하이닉스 일봉 보여주고 추세 정렬 봐줘\"*\n- **시장 스크리닝 → 후보 종목 분석까지 한 대화 안에서** — *\"거래대금 상위 종목을 기술적으로 분석해줘\"*\n- **두 개의 저장 신호를 합쳐 — HTS 한 화면으로는 못 쓰는 조건** (v1.4) — *\"이평 골든크로스(5,20), 외인 3일연속 순매수, 양쪽 다 잡힌 종목만\"*\n- **스크리닝 → 프로그램매매 footprint까지** (v1.1) — *\"방금 나온 4종목 중 NC소프트 프로그램 수급 흐름은?\"*\n- **분할 매수 평단 머지 + 액면분할 일괄 반영** — *\"한투에 10주 21.5만에 샀고… 5주 더 24만에 추가 매수… 100원 액면분할 빠뜨렸네\"*\n\n스크린샷·대화 흐름 전체는 [활용 사례 모음](docs/case-studies/usage-examples.md)에서.\n\n---\n\n## 설치 — 1분 컷\n\n**사전 준비.** `dnx`는 **.NET SDK 10 이상**에 들어 있는 dotnet 도구 실행기입니다. 아직 없으면 [.NET 다운로드](https://dotnet.microsoft.com/download/dotnet/10.0)에서 SDK를 먼저 설치하세요 (Windows/macOS/Linux 모두 지원). 터미널에서 `dnx --help`가 도움말을 출력하면 준비 완료입니다.\n\nLS증권 OpenAPI 키 한 쌍(`AppKey` + `AppSecretKey`)이 필요합니다 — **LS증권 → 고객센터 → 매매시스템 → API** 에서 발급. 실투용과 모의투자용은 *별도 키 페어*입니다 ([LS-API-QUIRKS §4.2d](docs/LS-API-QUIRKS.md)) — 한 모드를 쓰려면 그 모드 키를 `LS_APPKEY` / `LS_APPSECRETKEY`로 로드. **`LS_MARKET`은 같은 키를 모드만 바꿔 쓰는 스위치가 아니라, 현재 주입된 키가 실전용인지 모의용인지 명시하는 런타임 모드**입니다 — REST endpoint는 두 모드 동일, 라우팅은 키가 결정. 자세한 단계는 [영문 README](README.en.md#getting-an-api-key) 참조.\n\n### Claude Desktop / Claude Code\n\n`claude_desktop_config.json` (Claude Desktop) 또는 워크스페이스 루트의 `.mcp.json` (Claude Code)에 아래 한 덩어리를 붙여 넣고 호스트를 재시작합니다.\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"lsopenapi\": {\n      \"command\": \"dnx\",\n      \"args\": [\"RedoxNet.Mcp.LsOpenApi\", \"--yes\"],\n      \"env\": {\n        \"LS_APPKEY\": \"...\",       // 실투 키이면 실계좌, 모의투자 키이면 모의계좌가 응답\n        \"LS_APPSECRETKEY\": \"...\",\n        \"LS_MARKET\": \"real\"       // ls_accounts(live) 라벨 + 토큰 cache 분리. 키와 일치시키세요 (모의투자 키면 \"virtual\"). 페이퍼 포트폴리오는 mode 무관.\n      }\n    }\n  }\n}\n```\n\nCursor · Google Antigravity는 Claude Desktop과 같은 `mcpServers` JSON 스키마를 쓰므로 위 블록을 그대로 쓰고 *파일 경로만* 호스트별 위치로 바꾸시면 됩니다. Codex CLI (TOML) · VS Code (`servers` 키) · FieldCure AssistStudio (GUI 다이얼로그)는 형식이 달라 별도 예시 — 전체 호스트별 설정 예시와 환경 변수 목록은 [영문 README](README.en.md#quick-start)에 있습니다.\n\n**차트 인라인 렌더링은 호스트별로 다릅니다.** **[AssistStudio](https://github.com/fieldcure/fieldcure-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).\n\n---\n\n## 미국 / 해외주식 사용 시 추가 설정 (v1.3+)\n\nv1.3부터 미장(Nasdaq / NYSE / AMEX) 종목의 시세·차트·종목 검색을 지원합니다. **국내주식만 쓰실 분은 이 섹션을 건너뛰셔도 됩니다.** 미장 데이터를 받으려면 LS증권에서 약정 두 개를 추가로 신청해야 하지만 — **API 키는 그대로** 쓰면 됩니다. LS는 한 AppKey / AppSecretKey 페어에 약정 권한이 누적되는 모델입니다.\n\n### 신청 순서\n\n1. **[HTS 2004] 해외주식 거래신청** — 계좌에 미국주식 거래 권한을 추가합니다. LS xingTrader에서 화면번호 `2004` 또는 `해외시장 → 해외주식 → 거래신청`. 동의 문서 4종(외화증권 거래설명서 / 해외주식 투자위험고지 / 해외주식 직접투자 신고 등 유의사항 / 개인신용정보 필수동의서)에 동의 후 신청. 종합매매계좌 그대로 사용 가능 — 새 계좌 개설은 불필요합니다.\n\n2. **[HTS 2007] 해외주식 실시간 시세신청** — 미국은 무료입니다. 화면번호 `2007` 또는 `해외시장 → 해외주식 → 실시간 시세신청`. **비전문가(일반 개인 고객) 필수정보 등록**을 같이 처리해야 시세 권한이 부여됩니다. 신청하지 않으면 **15분 지연시세**가 기본값입니다. 장기간 LS HTS/MTS 미접속 또는 미국주식 거래가 없으면 LS 정책상 사전 통보 없이 자동 해지될 수 있으니 주기적으로 LS 클라이언트를 켜두는 게 안전합니다.\n\n3. **(만약 `대차거래서비스` 약정이 있으면) 먼저 해지** — LS 마이페이지 → 약정관리, 또는 `1544-9911` 콜로 해지. 대차거래 약정이 걸려있으면 다음 단계의 해외주식 OpenAPI 등록 화면이 차단됩니다.\n\n4. **[웹 마이페이지] 해외주식 OpenAPI 사용등록** — LS증권 → 마이페이지 → 매매시스템 → 사용등록/해지 → \"해외주식 API\" 라디오 선택 → `사용등록`. 같은 AppKey / AppSecretKey 페어에 권한만 추가되므로 `LS_APPKEY` / `LS_APPSECRETKEY` 환경변수는 그대로입니다.\n\n신청 직후부터 v1.3+ 도구가 동작합니다 — `ls_search_overseas_stock`, `ls_get_overseas_quote`, `ls_get_overseas_chart`, 그리고 미장 데이터셋에도 `ls_add_indicator` / `ls_reframe_chart` 후속 처리가 가능합니다.\n\n### 유의사항\n\n- **AppKey 추가 발급 없음** — 국내·미장이 같은 키 페어를 공유합니다. 환경변수 변경 불필요.\n- **Non-Display 제한** — LS의 NYSE / Nasdaq 라이선스는 Display-only입니다. 결과를 사용자가 직접 보는 AI 비서 시나리오는 Display 범위로 해석되며, 자동매매 봇 / 외부 서비스로의 시세 재배포는 LS 약관 위반 소지가 있습니다.\n- **수수료** — 미국주식 매매 수수료는 OPEN API 매체 0.25%. (시세 데이터 사용료는 별도 부과 없음.) v1.3 도구는 read-only라 매매수수료 발생 없음 — 향후 주문 기능이 추가될 경우의 비용 정보입니다.\n- **타임존** — 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 구간.\n\n---\n\n## 데이터와 보안\n\n- **내 페이퍼 포트폴리오·관심종목은 로컬 디스크에만** 저장됩니다 (`%LOCALAPPDATA%\\RedoxNet\\LsOpenApi\\portfolio.db`). 외부 송신은 없습니다. v1.6부터 LS 실계좌의 AcntNo + 지점명/계좌명 라벨도 같은 파일의 별도 `ls_accounts` 테이블에 자동 발견 시점에 저장됩니다 (실시간 잔고/주문 자체는 캐시하지 않고 매 호출마다 LS REST를 새로 침).\n- **브로커·시장 연동은 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에만 머뭅니다.\n- **자격증명(API 키)은 환경변수로만** 전달받습니다. 채팅·도구 인자·MCP 엘리시테이션 등 모델이 관찰할 수 있는 경로로는 절대 받지 않습니다 — 의도된 보안 설계이며, 상세 정책은 [영문 README](README.en.md#credential-handling-policy)에 있습니다.\n\n---\n\n## 면책 조항\n\n이 프로젝트는 **비공식 third-party MCP 서버**입니다. LS증권(LS Securities Co., Ltd.)과 공식적인 제휴·후원·승인 관계가 없으며, \"LS증권\" 및 관련 상표는 해당 권리자의 소유입니다.\n\n본 도구는 **정보 제공 목적의 시세·차트 데이터 조회용**입니다. 투자 자문이나 매매 권유가 아니며, 주식 거래에는 원금 손실을 포함한 위험이 따릅니다. 모든 투자 결정과 그에 따른 손익은 전적으로 사용자 본인의 책임입니다.\n\nAPI 사용 시 [LS증권 OpenAPI 이용 안내](https://openapi.ls-sec.co.kr/howto-use)를 참조하고, 사이트에 표시되는 정식 이용약관을 확인 후 준수하시기 바랍니다. 현재 범위는 **국내주식 중심의 read-only 시장 데이터 + 해외주식 시세·차트 조회**(해외 지수·환율·선물 스냅샷 포함) **+ LS 실계좌 read-only 조회**(v1.6 — 보유·잔고·주문이력·일일손익·기간손익·BEP·주문가능수량·신용한도) **+ 로컬 페이퍼 포트폴리오 노트**(다중 브로커, watchlist, 테마, JSON 백업/복구)입니다. **v1.7에서 주문 발주** 가 추가 예정입니다. 실시간 시세(WebSocket) 는 현재 고려 대상이 아닙니다.\n\n---\n\n## 관련 자료\n\n- 개발자용 기술 문서 — [README.en.md](README.en.md)\n- 릴리스 노트 — [Mcp](RELEASENOTES.Mcp.md) · [Core](RELEASENOTES.Core.md)\n- 사례 분석 — [좁은 구간에서도 한 번에 끝내는 토큰 효율 분석](docs/case-studies/v0.4.0-token-efficiency.md)\n- License — [MIT](LICENSE)\n",
  "bytes": 9886,
  "sha": "c8e9c90145ad8cf66b886a72a3701bc5bef97fea0782efbf29099783afb5c817",
  "repo_slug": "redoxnet/mcp-lsopenapi",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_redoxnet_lsopenapi_e135f809/readme"
}