NH투자증권 Open API — Local MCP Server

NH투자증권 Open API 를 Claude Desktop 등 MCP 클라이언트에서 바로 사용할 수 있게 해주는 로컬 MCP 서버입니다. 국내주식(krstock) 자산군의 시세·조회·주문 API 를 Claude 가 도구로 호출합니다.

• 인증 · 토큰 발급 · 헤더 · Input_0 봉투 처리를 서버가 자동으로 대신합니다.

• 131개 엔드포인트를 몇 개의 메타 도구로 노출해, 도구가 많아 성능이 떨어지는 문제를 피합니다.

• 주문(거래) API 는 기본 비활성이며, 명시적으로 켠 경우에만 사용됩니다.

현재 버전은 국내주식(krstock) 자산군만 포함한 MVP 입니다. 다른 자산군은 specs/ 폴더에 openapi.json 을 추가하면 확장됩니다(맨 아래 참고).

1. 사전 요건

1. Node.js 18 이상 — nodejs.org 에서 설치. (node -v 로 확인)

2. NH투자증권 Open API 앱키/시크릿 — 포털 www.nhplug.com 에서 발급.

3. API 서버 네트워크 접근 — 이 MCP 는 당신 PC 에서 *.nhplug.com API 서버로 직접 연결합니다. 사내망 등에서만 접근 가능한 환경이라면, MCP 를 실행하는 PC 도 그 네트워크에 있어야 합니다.

Related MCP server: Korean Finance MCP Server

2. 설치 및 실행

방법 A — 로컬 빌드 (지금 바로 사용)

# 저장소를 받은 폴더에서
npm install
npm run build

빌드가 끝나면 dist/index.js 가 생성됩니다. 이 경로를 Claude 설정에 등록합니다(3번 참고).

방법 B — npx (npm 배포 후)

배포가 완료되면 설치 없이 아래 한 줄 설정으로 사용할 수 있습니다.

"command": "npx",
"args": ["-y", "@nhplug/mcp-server"]

3. Claude Desktop 연결

Claude Desktop 설정 파일 claude_desktop_config.json 을 엽니다.

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

아래 내용을 추가합니다. (방법 A · 로컬 빌드 기준. 경로는 실제 설치 위치로 변경)

{
  "mcpServers": {
    "nhplug": {
      "command": "node",
      "args": ["C:\\path\\to\\nhplug-mcp\\dist\\index.js"],
      "env": {
        "NHPLUG_APP_KEY": "발급받은_APP_KEY",
        "NHPLUG_APP_SECRET": "발급받은_APP_SECRET",
        "NHPLUG_BASE_URL": "https://devmoapi.nhplug.com:8443",
        "NHPLUG_ENABLE_TRADING": "false"
      }
    }
  }
}

저장 후 Claude Desktop 을 완전히 종료했다가 다시 실행하면 nhplug 도구가 나타납니다.

키를 설정 파일에 직접 넣는 대신, 저장소 폴더에 .env 파일(.env.example 참고)을 두는 방식도 지원합니다.

4. 환경변수

접속 환경(Base URL)

5. 제공 도구

동작 흐름(메타 도구): list_apis 로 원하는 API 를 찾고 → describe_api 로 입력값을 확인한 뒤 → call_api 로 호출합니다. 자주 쓰는 현재가·잔고는 단축 도구로 한 번에 호출할 수 있습니다.

사용 예시 프롬프트

• "삼성전자(005930) 현재가 알려줘" → get_stock_price

• "국내주식 시세 관련 API 목록 보여줘" → list_apis

• "krstockQuoteCurrentDaily 는 어떤 입력이 필요해?" → describe_api

• "내 계좌 20101036881 잔고 조회해줘" → get_stock_balance

6. 주문(거래) 활성화 ⚠️

주문 API(매수/매도/정정/취소)는 실제 자산이 오가는 기능이라 기본적으로 숨겨져 있습니다. 활성화하려면:

1. NHPLUG_ENABLE_TRADING=true 로 설정하고 Claude Desktop 재시작.

2. 반드시 모의투자 환경(devmoapi/moapi) 에서 충분히 검증 후 사용하세요.

3. 실거래 환경에서는 Claude 가 주문을 실행하기 전에 사람이 직접 확인하는 절차를 권장합니다.

비활성 상태에서는 주문 도구가 list_apis 에도 표시되지 않고, call_api 로 시도해도 거부됩니다.

7. 연결 검증 (self-test)

Claude 에 붙이기 전에, API 서버 접근·인증이 정상인지 로컬에서 먼저 확인할 수 있습니다.

# .env 에 APP_KEY / APP_SECRET / BASE_URL 을 채운 뒤
node scripts/selftest.mjs

토큰 발급 → 삼성전자 현재가 조회까지 성공하면 전체 검증 통과 ✅ 가 출력됩니다.

8. 문제 해결

로그는 표준오류(stderr)로 출력됩니다: [nhplug-mcp] 시작됨 · baseUrl=... · trading=...

9. 자산군 확장

다른 자산군을 추가하려면 해당 openapi.json 을 specs/ 폴더에 <도메인>.openapi.json 이름으로 넣고 다시 빌드하면 됩니다. 예:

specs/
  krstock.openapi.json   ← 현재 포함
  gbstock.openapi.json   ← 추가 시 해외주식 자동 노출
  krfuture.openapi.json  ← 추가 시 국내파생 자동 노출

메타 도구(list_apis/describe_api/call_api)는 코드 수정 없이 새 자산군을 자동 인식합니다. (단축 도구는 자산군별로 추가 구현 가능)

라이선스

MIT. 문의: apisupport@nhsec.com