{"_id":"@2oolkit/kiwoom-cli","_rev":"3-de964a2291b90f8efd9b7ed5403a2ae3","name":"@2oolkit/kiwoom-cli","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@2oolkit/kiwoom-cli","version":"0.1.0","keywords":["kiwoom","키움증권","kiwoom-securities","cli","mcp","model-context-protocol","ai-agent","claude","cursor","stock","stocks","trading","korea","krx","kospi","kosdaq","rest-api","openapi","brokerage","finance","investing"],"author":{"name":"haeminmoon"},"license":"MIT","_id":"@2oolkit/kiwoom-cli@0.1.0","maintainers":[{"name":"haeminmoon","email":"mym0846@gmail.com"}],"homepage":"https://github.com/haeminmoon/kiwoom-cli#readme","bugs":{"url":"https://github.com/haeminmoon/kiwoom-cli/issues"},"bin":{"kiwoom-cli":"dist/index.js","kiwoom-mcp":"dist/mcp.js"},"dist":{"shasum":"79afc9be412a3603cb9c62f21c56e50819fc87bb","tarball":"https://registry.npmjs.org/@2oolkit/kiwoom-cli/-/kiwoom-cli-0.1.0.tgz","fileCount":11,"integrity":"sha512-KsweBTuh9UPaelh00/EQlK3MrJTafyrXk7QaQZo9Xe0xCBo09496BUExtuOe9JK/z/zFSQ3DuBy4L5SztBF/Kw==","signatures":[{"sig":"MEUCIQDxRoAzUgWG7D5hUGoGJMl5ehnNxIWilqD1wESgy4tl+QIgMKBbltpgO8W+vMcqNtQr45EaeAR6jQtBOyvJm5f9iDM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":403697},"type":"commonjs","engines":{"node":">=20"},"gitHead":"bec823e2a55acacff88ea17ee378248966d0fb9b","scripts":{"dev":"ts-node src/index.ts","lint":"node --max-old-space-size=8192 ./node_modules/typescript/bin/tsc --noEmit","test":"jest","build":"tsup","test:watch":"jest --watch","test:coverage":"jest --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"haeminmoon","email":"mym0846@gmail.com"},"repository":{"url":"git+https://github.com/haeminmoon/kiwoom-cli.git","type":"git"},"_npmVersion":"11.4.2","description":"CLI & MCP server for Kiwoom Securities (키움증권) REST API — quote stocks, query charts, manage your account, and place orders from the terminal","directories":{},"_nodeVersion":"24.4.1","dependencies":{"zod":"^3.24.4","commander":"^13.1.0","@modelcontextprotocol/sdk":"^1.27.1"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","tsup":"^8.3.0","ts-jest":"^29.2.5","ts-node":"^10.9.2","typescript":"^5.7.0","@types/jest":"^30.0.0","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/kiwoom-cli_0.1.0_1782118868656_0.4076410899814815","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@2oolkit/kiwoom-cli","version":"0.1.1","keywords":["kiwoom","키움증권","kiwoom-securities","cli","mcp","model-context-protocol","ai-agent","claude","cursor","stock","stocks","trading","korea","krx","kospi","kosdaq","rest-api","openapi","brokerage","finance","investing"],"author":{"name":"haeminmoon"},"license":"MIT","_id":"@2oolkit/kiwoom-cli@0.1.1","maintainers":[{"name":"haeminmoon","email":"mym0846@gmail.com"}],"homepage":"https://github.com/haeminmoon/kiwoom-cli#readme","bugs":{"url":"https://github.com/haeminmoon/kiwoom-cli/issues"},"bin":{"kiwoom-cli":"dist/index.js","kiwoom-mcp":"dist/mcp.js"},"dist":{"shasum":"cefd79cf1dd32ee6e0ba6b05ff2759c83464beac","tarball":"https://registry.npmjs.org/@2oolkit/kiwoom-cli/-/kiwoom-cli-0.1.1.tgz","fileCount":11,"integrity":"sha512-o1Pzgy4P5Nin5US1msTCTZVma7yU5Re/+ycCvpJgTZNEEbtnAjoUq2UDoH8h71jJyVjFK96z023UPFpnsH3oRQ==","signatures":[{"sig":"MEUCIE7zeg7Q4efHOWu51fMIBKaskXzs4Z3Km9MlT/wUBh23AiEAx5aKYkeY9mNDR04EyoBmMMiaEgMtwbL2hIiNIxBRdhk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":416403},"type":"commonjs","engines":{"node":">=20"},"scripts":{"dev":"ts-node src/index.ts","lint":"node --max-old-space-size=8192 ./node_modules/typescript/bin/tsc --noEmit","test":"jest","build":"tsup","test:watch":"jest --watch","test:coverage":"jest --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"haeminmoon","email":"mym0846@gmail.com"},"repository":{"url":"git+https://github.com/haeminmoon/kiwoom-cli.git","type":"git"},"_npmVersion":"11.4.2","description":"CLI & MCP server for Kiwoom Securities (키움증권) REST API — quote stocks, query charts, manage your account, and place orders from the terminal","directories":{},"_nodeVersion":"24.4.1","dependencies":{"zod":"^3.24.4","commander":"^13.1.0","@modelcontextprotocol/sdk":"^1.27.1"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","tsup":"^8.3.0","ts-jest":"^29.2.5","ts-node":"^10.9.2","typescript":"^5.7.0","@types/jest":"^30.0.0","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/kiwoom-cli_0.1.1_1782174998096_0.9260120824011271","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@2oolkit/kiwoom-cli","version":"0.1.2","description":"CLI & MCP server for Kiwoom Securities (키움증권) REST API — quote stocks, query charts, manage your account, and place orders from the terminal","author":{"name":"haeminmoon"},"license":"MIT","homepage":"https://github.com/haeminmoon/kiwoom-cli#readme","bugs":{"url":"https://github.com/haeminmoon/kiwoom-cli/issues"},"repository":{"type":"git","url":"git+https://github.com/haeminmoon/kiwoom-cli.git"},"keywords":["kiwoom","키움증권","kiwoom-securities","cli","mcp","model-context-protocol","ai-agent","claude","cursor","stock","stocks","trading","korea","krx","kospi","kosdaq","rest-api","openapi","brokerage","finance","investing"],"type":"commonjs","bin":{"kiwoom-cli":"dist/index.js","kiwoom-mcp":"dist/mcp.js"},"scripts":{"build":"tsup","dev":"ts-node src/index.ts","lint":"node --max-old-space-size=8192 ./node_modules/typescript/bin/tsc --noEmit","test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage","prepublishOnly":"npm run build"},"dependencies":{"@modelcontextprotocol/sdk":"^1.27.1","commander":"^13.1.0","zod":"^3.24.4"},"devDependencies":{"@types/jest":"^30.0.0","@types/node":"^22.10.0","jest":"^29.7.0","ts-jest":"^29.2.5","ts-node":"^10.9.2","tsup":"^8.3.0","typescript":"^5.7.0"},"engines":{"node":">=20"},"_id":"@2oolkit/kiwoom-cli@0.1.2","_nodeVersion":"24.4.1","_npmVersion":"11.4.2","dist":{"integrity":"sha512-Pnmo43ee/hBRnyxof+wc2UnEra3llBrobjsv3kQYFcrxBb7KuDhRob8FswJ8pMFlsw5Nln7x1FMLRQ2RkzoJgA==","shasum":"cac600772a8f2f3d697d31e002589649b30eb409","tarball":"https://registry.npmjs.org/@2oolkit/kiwoom-cli/-/kiwoom-cli-0.1.2.tgz","fileCount":11,"unpackedSize":436498,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCHyKl9QnIXN/8+CNW+oW4Gj25HPluxeO6F44N5TiihbgCIQC57oFlaJrknwZibXiYK911dUoympGxWPlygZmkWv6QzQ=="}]},"_npmUser":{"name":"haeminmoon","email":"mym0846@gmail.com"},"directories":{},"maintainers":[{"name":"haeminmoon","email":"mym0846@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/kiwoom-cli_0.1.2_1782180531557_0.961131011628308"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-22T09:01:08.371Z","modified":"2026-06-23T02:08:51.812Z","0.1.0":"2026-06-22T09:01:08.783Z","0.1.1":"2026-06-23T00:36:38.248Z","0.1.2":"2026-06-23T02:08:51.694Z"},"bugs":{"url":"https://github.com/haeminmoon/kiwoom-cli/issues"},"author":{"name":"haeminmoon"},"license":"MIT","homepage":"https://github.com/haeminmoon/kiwoom-cli#readme","keywords":["kiwoom","키움증권","kiwoom-securities","cli","mcp","model-context-protocol","ai-agent","claude","cursor","stock","stocks","trading","korea","krx","kospi","kosdaq","rest-api","openapi","brokerage","finance","investing"],"repository":{"type":"git","url":"git+https://github.com/haeminmoon/kiwoom-cli.git"},"description":"CLI & MCP server for Kiwoom Securities (키움증권) REST API — quote stocks, query charts, manage your account, and place orders from the terminal","maintainers":[{"name":"haeminmoon","email":"mym0846@gmail.com"}],"readme":"# kiwoom-cli\n\n> **키움증권 REST API**를 위한 CLI & MCP 서버 — 터미널이나 AI 에이전트에서 국내 주식 시세 조회, 차트, 계좌 조회, 주문까지.\n\n[![npm](https://img.shields.io/npm/v/@2oolkit/kiwoom-cli.svg)](https://www.npmjs.com/package/@2oolkit/kiwoom-cli)\n\n`kiwoom-cli`는 키움증권 공식 REST API(`api.kiwoom.com`)를 깔끔한 Commander.js CLI **와** Model Context Protocol(MCP) 서버로 감싼 도구입니다. 같은 기능을 셸에서도, Claude / Cursor 같은 MCP 클라이언트에서도 쓸 수 있습니다.\n\n- **인증 자동 처리** — OAuth2 액세스 토큰을 발급·캐시하고 만료 전에 알아서 갱신합니다.\n- **모든 조회** — 종목 기본정보, 현재가, 10단계 호가, 틱~년봉 차트, 일별주가, 체결강도, 계좌 잔고, 예수금, 미체결, 체결내역, 실현손익, 순위, 업종지수.\n- **주문** — 매수 / 매도 / 정정 / 취소 (현금·신용), 확인 절차 내장. MCP에서는 명시적 `confirm` 플래그 필요.\n- **실전 또는 모의** — 실전(`api.kiwoom.com`)과 모의투자(`mockapi.kiwoom.com`) 전환 가능.\n\n> ⚠️ **실제 자금 주의.** `real` 환경에서 `order` 명령은 실제 계좌에 실거래를 냅니다. 먼저 `mock`에서 연습하세요. 주문 도구는 명시적 확인 없이는 절대 실행되지 않습니다.\n\n## 설치\n\n```bash\nnpm install -g @2oolkit/kiwoom-cli\n```\n\nNode.js 20 이상 필요.\n\n## 빠른 시작\n\n```bash\n# 1. 키움 앱키 + 시크릿키 설정 (대화형)\nkiwoom-cli config init\n\n# 2. 토큰 발급 확인\nkiwoom-cli auth token\n\n# 3. 조회\nkiwoom-cli stock info 005930          # 삼성전자 기본정보\nkiwoom-cli market price 005930        # 현재가\nkiwoom-cli market orderbook 005930    # 10단계 호가\nkiwoom-cli chart day 005930 -n 20     # 최근 일봉 20개\nkiwoom-cli account balance            # 보유종목 + 손익\n```\n\n앱키 / 시크릿키는 [키움 Open API 포털](https://openapi.kiwoom.com/)에서 발급받습니다.\n\n## 설정\n\n설정은 `~/.kiwoom-cli/config.json`(권한 `0600`)에, 캐시된 토큰은 `~/.kiwoom-cli/token.json`(권한 `0600`)에 저장됩니다.\n\n```bash\nkiwoom-cli config set --env real --appkey <키> --secretkey <시크릿>\nkiwoom-cli config set --env mock          # 모의투자 서버로 전환\nkiwoom-cli config list\n```\n\n환경변수는 설정 파일에 없는 값만 보완합니다(설정 파일이 우선):\n\n| 변수 | 의미 |\n|---|---|\n| `KIWOOM_APPKEY` | 앱키 |\n| `KIWOOM_SECRETKEY` | 시크릿키 |\n| `KIWOOM_ENV` | `real` 또는 `mock` |\n\n```bash\nKIWOOM_APPKEY=... KIWOOM_SECRETKEY=... KIWOOM_ENV=real kiwoom-cli market price 005930\n```\n\n모든 명령은 `-o, --output <table|json>`을 지원합니다(기본값 `table`). 스크립트로 파싱할 땐 `json`을 쓰세요:\n\n```bash\nkiwoom-cli account balance -o json | jq '.acnt_evlt_remn_indv_tot[].stk_nm'\n```\n\n## 명령어\n\n### `auth` — 액세스 토큰\n```\nkiwoom-cli auth token [--force]      토큰 발급/재사용 + 캐시\nkiwoom-cli auth status               캐시된 토큰 + 만료시각 표시\nkiwoom-cli auth revoke               캐시된 토큰 폐기\n```\n\n### `stock` — 종목 정보 & 검색\n```\nkiwoom-cli stock info <코드>         기본정보 + 현재가 (ka10001)\nkiwoom-cli stock search <키워드>     종목 코드/이름 검색 (ka10099); -m 0=코스피/10=코스닥\nkiwoom-cli stock resolve <코드>      상장정보 (ka10100)\nkiwoom-cli stock members <코드>      상위 5개 매수/매도 거래원 (ka10002)\nkiwoom-cli stock credit-trend <코드> 신용매매동향 (ka10013)\n```\n\n### `market` — 시세, 호가, 체결\n```\nkiwoom-cli market price <코드>          현재가 스냅샷 (ka10007)\nkiwoom-cli market orderbook <코드>      10단계 호가 (ka10004)\nkiwoom-cli market after-hours <코드>    시간외 단일가 (ka10087)\nkiwoom-cli market daily <코드>          일별주가 (ka10086)\nkiwoom-cli market trades <코드>         최근 체결 (ka10003)\nkiwoom-cli market strength <코드>       체결강도 (ka10046/47); --daily\nkiwoom-cli market inst-foreign <코드>   기관/외국인 매매추이 (ka10045)\n```\n\n### `chart` — OHLC\n```\nkiwoom-cli chart tick  <코드> [-s 1|3|5|10|30]            틱차트 (ka10079)\nkiwoom-cli chart min   <코드> [-i 1|3|5|10|15|30|45|60]   분봉 (ka10080)\nkiwoom-cli chart day   <코드> [-d YYYYMMDD]               일봉 (ka10081)\nkiwoom-cli chart week  <코드>                             주봉 (ka10082)\nkiwoom-cli chart month <코드>                             월봉 (ka10083)\nkiwoom-cli chart year  <코드>                             년봉 (ka10094)\n```\n모두 `-n, --count <n>`(봉 개수, 기본 50), `--raw`(수정주가 미적용), `-p, --paginate`(강제 다중 페이지) 지원.\n\n**1회 요청당 최대 봉 개수 (per-request cap)** — 그 이상은 `cont-yn`/`next-key` 헤더로 **자동 페이지네이션**:\n\n| 차트 | 1회 최대 | `--count` 한도 |\n|---|---|---|\n| tick / min | 900 | 100,000 (자동 분할) |\n| day | 600 | 100,000 (자동 분할) |\n| week | 300 | 100,000 (자동 분할) |\n| month | 240 | 100,000 (자동 분할) |\n| year | 30 | 100,000 (자동 분할) |\n\n`--count`가 1회 최대를 넘으면 자동으로 여러 페이지를 받아 합칩니다(시간순 정렬·중복 제거는 API 순서를 그대로 유지). `-p/--paginate`로 강제할 수도 있습니다. `--count`는 양의 정수여야 하며 100,000으로 클램프됩니다.\n\n```bash\nkiwoom-cli chart day 005930 -n 600              # 한 페이지(최대) — 일봉 600개\nkiwoom-cli chart day 005930 -n 2000 -o json     # 자동 페이지네이션 — 일봉 ~2000개\nkiwoom-cli chart min 005930 -i 1 -n 2000 -o json # 1분봉 ~2000개 (여러 페이지)\n```\n\n### `account` — 계좌\n```\nkiwoom-cli account balance              평가잔고 + 보유종목 (kt00018)\nkiwoom-cli account deposit              예수금/주문가능/출금가능 (kt00001)\nkiwoom-cli account eval                 평가현황 + 보유종목 (kt00004)\nkiwoom-cli account settled              체결잔고 (kt00005)\nkiwoom-cli account open-orders [-c 코드] 미체결 주문 (ka10075)\nkiwoom-cli account executions [-c 코드]  체결 내역 (ka10076)\nkiwoom-cli account order-detail          주문체결 상세내역 (kt00007)\nkiwoom-cli account pnl <코드> [-s -e]    실현손익 (ka10072/73, 최대 3개월)\nkiwoom-cli account journal               당일매매일지 (ka10170)\nkiwoom-cli account returns [-s -e]       일별계좌수익률 (kt00016)\n```\n\n### `ranking` & `sector` — 순위 & 업종\n```\nkiwoom-cli ranking fluctuation [-s 1..5]  전일대비 등락률 순위 (ka10027)\nkiwoom-cli ranking volume                 당일 거래량 상위 (ka10030)\nkiwoom-cli ranking amount                 거래대금 상위 (ka10032)\nkiwoom-cli ranking surge                  거래량 급증 (ka10023)\nkiwoom-cli ranking prev-volume            전일 거래량 상위 (ka10031)\nkiwoom-cli ranking net-buy [옵션]         수급: 외국인·기관 순매수 상위 (ka90009)\n\nkiwoom-cli sector price [-m -c]   업종 현재가 (ka20001)\nkiwoom-cli sector stocks          업종 구성종목 (ka20002)\nkiwoom-cli sector all             전업종 지수 (ka20003)\nkiwoom-cli sector daily           업종 일별지수 (ka20009)\nkiwoom-cli sector codes           업종 코드 목록 (ka10101)\n```\n순위: `-m 000=전체/001=코스피/101=코스닥`, `-x 1=KRX/2=NXT/3=통합`.\n\n수급(`net-buy`, alias `supply`)은 한 번의 ka90009 호출로 외국인·기관 매매상위를 함께 반환합니다:\n`-b foreign|institution|both`(기본 both), `--side buy|sell`(기본 buy=순매수), `-n <1-50>`(기본 10), `-q 1=금액/2=수량`(기본 1), `-d YYYYMMDD`(기본 최신). 예: `kiwoom-cli ranking net-buy -b both -n 10`.\n\n### `order` — ⚠ `real`에서는 실제 자금\n```\nkiwoom-cli order buy  <코드> <수량> [-p 가격] [-t 유형] [-x KRX|NXT|SOR] [--credit] [-y]\nkiwoom-cli order sell <코드> <수량> [-p 가격] [-t 유형] [-x ...] [--credit] [-y]\nkiwoom-cli order modify <주문번호> <코드> <수량> <가격> [-x ...] [--credit] [-y]\nkiwoom-cli order cancel <주문번호> <코드> [-q 수량] [-x ...] [--credit] [-y]\n```\n- `-p/--price`를 생략하면 **시장가**, 지정하면 **지정가** 주문.\n- `-t/--type`으로 주문유형(`trde_tp`) 지정: `0`=지정가, `3`=시장가, `5`=조건부지정가, `6`=최유리, `7`=최우선, `10/13/16`=IOC, `20/23/26`=FOK, `28`=스톱지정가, …\n- 스톱지정가(`28`)는 `--cond-price <트리거가>` 필요.\n- 각 명령은 요약을 출력하고 **확인을 묻습니다**. `-y/--yes`로 건너뛸 수 있습니다.\n\n```bash\nkiwoom-cli order buy  005930 1 -p 70000     # 지정가 매수 1주 @ 70,000\nkiwoom-cli order sell 005930 1              # 시장가 매도 1주\nkiwoom-cli order cancel 0000139 005930      # 잔량 전부 취소\n```\n\n## MCP 서버\n\n모든 조회 도구와 (가드 적용된) 주문 도구를 MCP 클라이언트에 노출합니다.\n\n```jsonc\n// Claude Desktop / Cursor mcp 설정\n{\n  \"mcpServers\": {\n    \"kiwoom\": {\n      \"command\": \"kiwoom-mcp\",\n      \"env\": {\n        \"KIWOOM_APPKEY\": \"발급받은-앱키\",\n        \"KIWOOM_SECRETKEY\": \"발급받은-시크릿키\",\n        \"KIWOOM_ENV\": \"real\"\n      }\n    }\n  }\n}\n```\n\n도구: `get_stock_info`, `get_price`, `get_orderbook`, `get_daily_price`, `get_recent_trades`, `search_stocks`, `get_chart`, `get_balance`, `get_deposit`, `get_open_orders`, `get_executions`, `get_realized_pnl`, `get_ranking`, `get_net_buy_ranking`, `get_sector`, `place_order`, `modify_order`, `cancel_order`.\n\n주문 도구는 **`confirm: true`를 넘기지 않으면 미리보기만 반환하고 아무것도 실행하지 않습니다** — 에이전트가 실수로 실주문을 낼 수 없습니다.\n\n## 데이터에 관한 참고\n\n- 숫자는 0으로 채워진 문자열로 옵니다. CLI가 패딩을 제거하고 천 단위로 끊어 표시합니다.\n- 시세/차트 가격에는 **방향 부호**가 붙습니다(`-353750` = 가격 353,750, 전일 종가 *대비 하락*). CLI는 절대값을 표시하고 등락은 별도로 보여줍니다.\n- 페이지네이션(`cont-yn`/`next-key`)은 필요한 곳에서 자동 처리됩니다.\n- 데이터 없음 응답(`return_code: 20`)은 오류가 아닌 빈 결과로 처리합니다.\n\n## 개발\n\n```bash\nnpm install\nnpm run build        # tsup → dist/index.js (CLI) + dist/mcp.js (MCP)\nnpm test             # jest\nnpm run lint         # tsc --noEmit\n```\n\n## 라이선스\n\nMIT\n","readmeFilename":"README.md"}