NH투자증권이 2026년 8월 10일 내놓은 나무증권 API 플러그(Namuh PLUG)는 REST 방식의 OpenAPI다. 그리고 공식 GitHub에 클로드(Claude) 데스크톱에 바로 물릴 수 있는 MCP 샘플이 올라와 있다. 이 글은 그 샘플로 나무증권 API 신청부터 앱키 발급, 설치, 클로드 연결, 삼성전자 현재가와 계좌 잔고 조회까지 하루 저녁에 실제로 돌려본 기록이다.
먼저 결론부터 적는다. 신청은 즉시 승인이었고, 설치에서 클로드 연결까지 실제로 걸린 지점은 네 군데였다. 대화로 시세와 잔고는 조회되지만 주문은 되지 않았다. 주문이 안 되는 것은 결함이 아니라 설계다. 그 경계선이 이 글의 핵심이다.
나무증권 API, 무엇이 달라졌나
PLUG는 HTTPS 기반 REST OpenAPI라 Windows, Mac, Linux 어디서든 쓸 수 있다. 과거 증권사 개발자 도구가 특정 운영체제와 개발 환경에 묶여 있던 것과 달리, HTTP 요청을 보낼 수 있는 언어와 환경이면 무엇이든 접근할 수 있다는 점이 핵심이다.
| 방식 | REST OpenAPI (HTTPS) |
| 출시 | 2026년 8월 10일 |
| 엔드포인트 | REST 49개, 실시간 27채널 |
| 인증 | 앱키·시크릿으로 접근토큰 발급 (24시간 유효) |
| 사용료 | 별도 항목 없음. 매매 시 수수료만 (국내 0.01%, 해외 0.09%) |
| AI 연결 | 공식 GitHub에 로컬 MCP 샘플 (TypeScript, MIT) |
주의할 점 하나. PLUG 자체는 MCP가 아니다. MCP는 클로드 같은 AI 앱이 외부 도구를 부르는 규격이고, NH가 그 규격에 맞춘 샘플 서버를 따로 공개한 것이다. 이 글에서 “클로드에 연결한다”는 말은 이 샘플 서버를 클로드 데스크톱에 등록한다는 뜻이다.
신청부터 앱키 발급까지
조건은 NH투자증권 계좌와 나무증권 앱이다. nhplug.com에서 QR 또는 인증서로 로그인하면 “API 사용신청” 버튼이 있고, 신청하면 앱키(APPKEY)와 시크릿이 발급된다. 고객번호당 1개이며 보유 계좌 전체에 공용이다. 상세 조건은 나무증권 PLUG 공식 안내에 있다.
실측 결과 신청 시각은 2026년 8월 25일 20시 55분이었고, 같은 화면에서 곧바로 앱키를 받을 수 있었다. 사실상 즉시 승인이다. 유효기간은 1년(2027년 8월 25일까지)으로 표시됐다. 다만 서비스가 반드시 1년간 유지된다는 뜻은 아니다. 공식 안내에는 3개월 단위로 미거래 시 익월 첫 영업일에 자동해지되며, 모의투자 서버로만 로그인한 경우에도 자동해지될 수 있다고 적혀 있다.
신청 완료 화면에는 등록 계좌 목록이 뜨는데, 나중에 API로 계좌목록을 조회하면 이 화면보다 많은 계좌가 돌아온다. 화면은 대표 계좌만 보여주고 API는 고객번호에 묶인 계좌 전체를 주는 구조로 보인다. 어느 계좌가 어떤 용도인지는 코드로만 오기 때문에 사용자가 알고 있어야 한다.
클로드에 연결한다는 것의 의미
여기서 한 번 정리해 둘 것이 있다. 클로드는 세 가지 형태로 쓸 수 있다. 웹(claude.ai), 크롬 확장 사이드패널, 그리고 데스크톱 앱이다. 로컬 MCP 서버를 실행할 수 있는 것은 데스크톱 앱뿐이다. 웹이나 확장에서는 아무리 설정해도 나무증권 도구가 나타나지 않는다.
연결 구조는 단순하다. 데스크톱 앱이 설정 파일에 적힌 명령으로 nhplug-mcp 서버를 로컬에서 띄우고, 그 서버가 앱키로 NH 서버에 토큰을 받아 API를 대신 호출한다. 앱키는 내 PC의 설정 파일에만 있고 클로드 서버로 올라가지 않는다. 다만 클로드가 답변에 사용하는 계좌목록·잔고 등 조회 결과는 대화 처리 대상이 되므로, 금융정보를 AI 대화에 전달한다는 점은 별도로 고려해야 한다.
연결 실측: 설정 파일 한 블록이면 끝난다
순서는 네 단계다. Node.js 설치, 샘플 서버 빌드, 설정 파일 등록, 앱 재시작.
① Node.js. 실측 PC에는 Node가 없었다. PowerShell에서 winget install OpenJS.NodeJS.LTS 한 줄로 설치했고, 새 창에서 node -v가 v24.19.0을 돌려줬다.
② 샘플 서버 빌드. nhplug-mcp 공식 저장소를 zip으로 받아 풀고 npm install, npm run build를 돌렸다. 98개 패키지, 취약점 0, 8초. README는 npx -y github:PLUG-OpenAPI/nhplug-mcp 한 줄 방식도 안내하지만, 첫 실행에 1분 가까이 걸리고 캐시 갱신 문제가 있어 로컬 빌드 쪽이 안정적이었다.
③ 설정 파일. 클로드 데스크톱의 설정 → 개발자 → 구성 편집을 누르면 claude_desktop_config.json이 열린다. 여기에 아래 블록을 넣는다.
{
"mcpServers": {
"nhplug": {
"command": "node",
"args": ["C:\\경로\\nhplug-mcp\\dist\\index.js"],
"env": {
"NHPLUG_APP_KEY": "앱키",
"NHPLUG_APP_SECRET": "시크릿",
"NHPLUG_BASE_URL": "https://api.nhplug.com:8443"
}
}
}
}이미 다른 MCP 서버가 등록돼 있다면 기존 mcpServers 안에 nhplug 블록만 추가하면 된다.
④ 재시작. 창을 닫는 것으로는 부족하다. 트레이 아이콘에서 완전 종료한 뒤 다시 실행해야 설정을 읽는다. 실측에서는 프로세스를 강제 종료하고 나서야 개발자 화면에 nhplug running이 떴다.
검증: 토큰 발급에서 삼성전자 현재가까지
클로드에 붙이기 전에 샘플 저장소에 들어 있는 자가진단 스크립트를 먼저 돌리는 편이 낫다. .env 파일에 앱키·시크릿·BASE_URL 세 줄을 넣고 node scripts/selftest.mjs를 실행하면 토큰 발급과 삼성전자(005930) 현재가 조회를 순서대로 시도한다.
여기서 통과하면 설정 파일 문제만 남는다. 여기서 막히면 앱키나 네트워크 문제이므로 클로드 쪽을 만질 이유가 없다.
대화로 무엇이 되나
연결되면 클로드에 도구 6개가 나타난다. 단축 도구 3개(현재가·잔고·계좌목록)와 메타 도구 3개(API 목록·API 설명·API 호출)다.
“삼성전자 현재가 알려줘”라고 물으면 현재가 도구가 호출되고, 응답에는 현재가뿐 아니라 10단계 호가와 잔량, 최근 체결 30건, 거래원 상위 5개, PER·PBR, 52주 고저, 외국인 보유율까지 한 번에 들어온다. 응답 코드 00000이 정상이다.
“내 잔고 보여줘”는 계좌번호가 필요하다. 계좌목록 도구가 먼저 호출돼 계좌번호와 유형 코드를 받고, 그다음 잔고 도구가 보유 종목·수량·매입단가·현재가·평가손익을 돌려준다. 이때 응답 코드는 00166이었는데, 샘플 서버는 이를 정상 코드로 취급한다. HTTP 200이면서 업무 코드로 성공·실패를 구분하는 방식이라 코드 목록을 알아둘 필요가 있다.
“사용할 수 있는 API 목록 보여줘”를 치면 메타 도구가 국내주식 23개, 해외주식 12개, 합계 35개를 돌려준다. 그리고 “주문 API 14개는 안전을 위해 기본 비활성이며 숨겨져 있다”는 안내가 같이 온다. 35 더하기 14는 49로, 공식 문서의 REST 49개와 맞는다.
한 가지 짚어둘 것이 있다. 잔고 응답의 삼성전자 현재가는 261,000원이었는데 같은 시각 현재가 API는 257,000원이었다. 잔고 쪽이 시간외 가격을 반영했을 가능성이 있으나 확인하지 못했다. 두 API의 가격 기준이 다를 수 있다는 점은 기억해 둘 필요가 있다.
주문은 왜 안 되나
이 글에서 가장 중요한 부분이다. 주문이 안 되는 이유는 두 겹이다.
첫째, 샘플 서버가 막는다. 환경변수 NHPLUG_ENABLE_TRADING이 기본 false이고, 이 상태에서는 주문 API 14개가 도구 목록에서 아예 빠진다. 켜려면 설정 파일에 true를 넣고 앱을 다시 띄워야 하며, 공식 안내는 “실제 주문이 체결될 수 있으니 반드시 모의투자 환경에서 충분히 검증한 뒤 사용하라”고 적고 있다.
둘째, 클로드가 막는다. “종합계좌에서 삼성전자 1주 사줘”라고 실제로 요청하자 클로드는 주문 도구가 없다는 점과 별개로 “도구가 있더라도 주식 매수·매도 같은 금융 거래는 대신 실행하지 않는다”며 앱에서 직접 하라고 답했다. README도 “거래 도구가 노출될 뿐 클로드가 실제 주문을 실행하지는 않는다”고 명시한다.
그래서 이 조합의 용도는 조회와 분석이다. 보유 종목의 손익을 대화로 확인하고, 호가와 체결을 읽어 달라고 하고, 여러 종목을 비교해 달라고 하는 데까지다. 매매 판단을 AI에 맡기는 구조가 아니다. 개인적으로는 이 경계가 오히려 안심되는 지점이라고 본다. 앱키 하나로 주문까지 나가는 구조였다면 설정 파일 한 줄 실수가 곧 사고다.
자동매매로 가려면
주문 자동화가 목적이라면 경로가 다르다. NH는 파이썬 SDK(pip install nhplug)를 따로 제공하며, 여기서는 주문 API를 직접 호출할 수 있다. 다만 모의투자 API 서버(moapi) 자체는 접근토큰을 발급하지 않는다. 모의투자를 쓸 때도 토큰은 운영 인증 서버에서 받고, 실제 API 호출 대상만 moapi로 바꾸는 구조다(샘플 서버에서는 NHPLUG_AUTH_URL과 NHPLUG_BASE_URL을 분리해 지정). 이 부분은 별도 글에서 다룬다.
AI를 종목 리서치에 쓰는 방법 자체는 챗GPT 주식 활용법과 클로드 주식 분석 실측에 정리해 뒀다. 이 글의 API 연결은 그 위에 실시간 시세와 내 계좌 데이터를 얹는 단계다.
걸린 것들
실측 중 실제로 막혔던 지점을 순서대로 적는다.
- Node 부재. 처음부터
node가 없다는 오류가 났다. winget 한 줄로 해결됐지만, 설치 후 PowerShell 창을 새로 열어야 인식된다. - git 부재.
git clone도 없다는 오류가 났다. git을 설치하는 대신 GitHub의 zip 다운로드로 우회했다. - 설정 파일 위치. 스토어판 클로드 데스크톱은 설정 파일이
%APPDATA%\Claude가 아니라%LOCALAPPDATA%\Packages\Claude_...\LocalCache\Roaming\Claude아래에 있다. 경로를 직접 찾지 말고 앱의 “구성 편집” 버튼으로 여는 편이 확실하다. - 재시작. 창 닫기로는 설정이 다시 읽히지 않는다. 완전 종료가 필요하다.
- N2 계정. 나무증권이 아니라 NH투자증권 N2 계정이면
NHPLUG_BASE_URL과NHPLUG_AUTH_URL두 개를 모두 n2plug 도메인으로 바꿔야 한다. - 유량 제한. 초당 5회이며 자동 재시도가 없다. 이번 실측에서는 단건 조회만 해 한도에 걸리지 않았다.
- 업무 오류. HTTP 200이어도
rsp_cd가 성공 코드가 아니면 실패다. 샘플 서버의 기본 성공 코드는00000, 00166, 00221, 13578이다.
자주 묻는 질문
나무증권 API 신청은 어떻게 하나요?
NH투자증권 계좌와 나무증권 앱이 있으면 nhplug.com에서 QR 또는 인증서로 로그인해 “API 사용신청”을 누르면 된다. 실측에서는 신청 직후 바로 앱키가 발급됐고 화면에 표시된 유효기간은 1년이었다. 다만 미거래에 따른 서비스 자동해지 조건은 별도로 적용된다.
나무증권 API 키는 어디서 확인하나요?
nhplug.com 로그인 후 서비스 신청현황 화면에서 앱키를 확인할 수 있고, 시크릿은 별도의 시크릿조회 메뉴로 다시 볼 수 있다. 앱키는 고객번호당 1개이며 여러 계좌에 공용으로 쓴다.
파이썬으로도 되나요?
된다. NH가 pip install nhplug로 설치하는 파이썬 SDK를 제공한다. 이 글의 클로드 연결은 TypeScript 샘플 서버를 쓰지만, 나무증권 API 자체는 언어를 가리지 않는다.
자동매매가 가능한가요?
API 수준에서는 가능하다. 다만 클로드 연결 샘플에서는 주문 도구가 기본 비활성이고, 켜더라도 클로드가 실제 주문을 실행하지 않는다. 자동매매는 파이썬 SDK로 직접 구현하는 경로다.
수수료는 얼마인가요?
API 사용료 항목은 별도로 없다. 매매가 발생하면 국내주식 0.01%, 해외주식 0.09%의 수수료가 적용되며, 그 외 상품은 온라인 매매 수수료를 따른다. 조회만 하면 비용이 없다.
기존 나무증권 Open API와 무엇이 다른가요?
PLUG는 HTTPS 기반 REST 방식이라 운영체제 제약 없이 HTTP 요청을 보낼 수 있는 어떤 언어에서든 쓸 수 있다. 특정 운영체제와 개발 환경에 묶여 있던 과거 방식과 가장 크게 다른 점이다.
클로드 말고 다른 AI에서도 되나요?
샘플 서버는 MCP 규격이라 MCP를 지원하는 클라이언트라면 이론상 연결된다. 다만 공식 README는 클로드 데스크톱 기준으로만 안내하며, 이 글에서도 클로드만 실측했다.
모의투자로 먼저 해볼 수 있나요?
있다. 다만 모의투자 서버(moapi)는 토큰을 발급하지 않으므로, 토큰은 운영 인증 서버에서 받은 뒤 API 호출 대상만 moapi로 지정해야 한다. 조회 API는 운영 환경에서 바로 시험해도 위험이 없고, 주문 검증은 이 방식으로 모의투자에서 먼저 하는 편이 낫다.
이 글은 정보 제공 목적일 뿐이다. 언급된 어떤 종목에 대해서도 매수·매도 추천이 아니며, 투자 판단과 그 결과는 각자의 몫이다.
최종 확인: 2026-08-25
