HERMETIX

MCP 서버 · 로컬 전용 · 조회 전용 · MIT

AI 에게 내 증권 계좌를 물어보세요

hermetix-mcp 를 등록하면 Claude Desktop·Claude Code·Cursor 에서 넥스트·한국투자·키움·NH·LS·DB·토스·KB 의 시세와 계좌, 보유 종목, 주문 내역을 대화로 조회할 수 있습니다. hermetix SDK 위에서 내 PC 에서만 돌아갑니다.

설치 가이드npm
대화 예시예시

한투 모의 계좌 보유 종목이랑 수익률 보여줘

hermetix · get_holdings(account: "kis-paper")

3종목을 보유 중입니다. 평가금액 합계는 약 120만 원이고, 수익률이 가장 높은 종목은 삼성전자(+4.2%)입니다.

시작하기

Node.js 22 이상과 증권사 Open API 키가 필요합니다. 5분이면 됩니다.

  1. 1

    키 파일 만들기

    ~/.hermetix/mcp.json 에 계좌를 별칭과 함께 적습니다. 키는 이 파일에만 있고 AI 대화에는 실리지 않습니다.

    ~/.hermetix/mcp.json
    {
  "accounts": {
    "kis-paper": {
      "broker": "kis",
      "apiKey": "앱키",
      "apiSecret": "앱시크릿",
      "account": "계좌번호 앞 8자리"
    },
    "toss": { "broker": "toss", "apiKey": "client_id", "apiSecret": "client_secret" }
  },
  "default": "kis-paper"
}
    $chmod 600 ~/.hermetix/mcp.json
  2. 2

    AI 클라이언트에 등록하기

    터미널에서 한 줄

    $claude mcp add hermetix -- npx -y hermetix-mcp
  3. 3

    확인하기

    새 대화에서 "내 hermetix 계좌 목록 보여줘" 라고 물어보세요. 등록한 별칭·증권사·모의/실전이 나오면 끝입니다.

할 수 있는 것

10개 tool, 8개 증권사 공통. 결과는 증권사와 무관하게 같은 모양입니다.

기능이렇게 물어보세요
계좌 목록list_accounts"등록된 계좌 보여줘"
현재가get_quotes"삼성전자, SK하이닉스 현재가"
캔들get_candles"삼성전자 최근 30일 일봉"
장 운영일get_calendar"다음 개장일 언제야?"
계좌 요약get_account"계좌 평가금액이랑 예수금"
보유 종목get_holdings"보유 종목이랑 수익률"
매수 가능 금액get_buying_power"지금 매수 가능 금액"
주문 목록list_orders"최근 주문 상태"
주문 상세get_order"방금 그 주문 체결됐어?"
체결 내역get_fills"오늘 체결 내역"

주문을 넣거나 취소하는 기능은 없습니다. 금액은 소수 문자열, 계좌번호는 앞 4자리만 보입니다.

증권사별 설정

broker 와 account 만 증권사마다 다릅니다. 실전 계좌는 environment: LIVE 를 넣습니다.

증권사brokeraccount기본 환경
넥스트증권next계좌 ID (생략 시 acc_main)모의
한국투자증권kis필수 — 계좌번호 앞 8자리모의
키움증권kiwoom쓰지 않음모의
NH투자증권nh계좌번호 (생략 시 첫 계좌)모의
LS증권ls쓰지 않음모의
DB증권db쓰지 않음모의
토스증권toss계좌 순번 (생략 시 첫 위탁계좌)실전 전용
KB증권kb쓰지 않음실전 전용

증권사별 추가 항목(hts_id, mac_address 등)은 브로커 팩토리 문서의 이름 그대로 넣습니다.

안전 설계

키는 내 PC 에만

내 PC 에서 실행되는 로컬 서버입니다. 키는 내 기기에서 증권사로만 가고, AI 대화나 hermetix 서버로 가지 않습니다.

조회 전용

주문·취소 tool 이 아예 없습니다. AI 가 잘못 이해해도 주문은 나가지 않습니다.

계좌번호는 가린다

응답에는 계좌번호 앞 4자리만 실립니다. 키 파일 권한이 600 이 아니면 실행 시 경고합니다.

자주 묻는 질문

Claude Desktop 의 "커스텀 커넥터 추가" 로는 안 되나요?+

커스텀 커넥터는 인터넷에 있는 원격 서버(URL) 용입니다. hermetix-mcp 는 키를 밖으로 보내지 않으려고 내 PC 에서만 도는 로컬 서버라, 설정 파일(claude_desktop_config.json)에 등록합니다.

키를 파일에 두기 싫어요.+

값 자리에 "env:변수이름" 을 쓰면 환경변수에서 읽습니다. 단 Claude Desktop·Cursor 는 터미널 밖에서 실행돼 ~/.zshrc 의 변수를 못 봅니다 — 키를 담은 env 파일을 실행할 때 불러오게 등록하세요 (가이드 참고).

토스 해외 주식 손익이 앱과 달라요.+

미국 종목의 평가손익은 달러 그대로 보여 줍니다(평가금액만 원화). 토스 앱의 원화 손익에는 매수 당시 환율의 환차손익이 들어가는데, 토스 API 가 종목별 원화 원금을 주지 않아 같은 값을 만들 수 없습니다.

연결이 안 되거나 "Permission denied" 가 떠요.+

새 버전을 받다가 설치가 끊기면 npx 캐시가 깨질 수 있습니다. 터미널에서 rm -rf ~/.npm/_npx 후 앱을 다시 여세요. Claude Desktop 로그는 ~/Library/Logs/Claude/mcp-server-hermetix.log 에 있습니다.

사용량 데이터를 보내나요?+

SDK 와 같은 익명 집계(증권사·기능별 성공/에러 건수, 응답 시간)만 보냅니다. 키·계좌·종목·금액은 보내지 않습니다. 이 데이터가 사용량 랭킹과 API 현황이 됩니다.

증권사별 항목, 여러 계좌, 문제 해결 전체는 설치 가이드 → · 연결이 안 되면 Discord 에서 질문 →