NH투자증권 Open API MCPサーバー
コミット 2026年11月13日NH Investment & Securities Open APIを使用して、国内および海外の株式市場価格や口座残高をAIクライアントから照会できます。
別名 PLUG-OpenAPI/nhplug-mcp
- スター
- 16
- ツール
- —
- ダウンロード数(30日間)
- —
- 最新バージョン
- —
- 最終コミット
- 2026年11月13日
- ライセンス
- MIT
NH투자증권 Open API MCPとは
NH Investment & Securities Open APIを使用して、国内および海外の株式市場価格や口座残高をAIクライアントから照会できます。
プロジェクトのREADMEから生成された概要
NH투자증권 Open API MCP server について
nhplug-mcpは、ClaudeやChatGPTの中から国内および海外の株式市場価格や口座残高を照会することを投資家に可能にします。このローカルMCP serverは、AIクライアントをNH Investment & Securities Open APIに接続し、自然言語を通じて金融データとのやり取りを実現します。認証、トークン発行、ヘッダー管理などの複雑なタスクを自動的に処理するため、ポートフォリオを確認するためにコードを書く必要はありません。
このサーバーは、国内株式(krstock)および海外株式(gbstock)をカバーする53個のREST APIと27個のリアルタイムチャネルへのアクセスを提供します。list_apis、describe_api、call_apiといったメタツールを使用することで、AIに大量の個別のツールを渡して負荷をかけることなく、幅広い機能を提供します。使用するには、デスクトップクライアントの設定で環境変数としてNHPLUG_APP_KEYとNHPLUG_APP_SECRETを指定する必要があります。なお、このサーバーは厳密に照会目的であり、売買注文を実行することはありません。
できること
- 1現在の株価を確認する特定の銘柄コードの最新市場価格を取得するようAIに依頼します。
- 2口座残高を監視する口座番号を使用して、現在の保有資産と口座残高の要約をリクエストします。
- 3利用可能な金融APIを探索する照会可能な特定の市場データAPIがどれであるかをAIを使って特定します。
- 4APIの入力要件を調査する特定の金融データエンドポイントを呼び出すために必要な正確なパラメータを確認します。
プロジェクトの README から作成されています。すべてのユースケースは、その引用と照らし合わせて確認されています。
設定
NHPLUG_APP_KEYNHPLUG_APP_SECRETNHPLUG_AUTH_URLNHPLUG_BASE_URL
| 名前 | 説明 | 種類 |
|---|---|---|
| NHPLUG_APP_KEY | — | |
| NHPLUG_APP_SECRET | — | |
| NHPLUG_AUTH_URL | — | |
| NHPLUG_BASE_URL | — |
自動チェック
実行日 2026年11月14日完全なレポート →まだ検証されていません。サーバーには80点のスコア、重大な問題がないこと、および検証に必要な十分なデータが必要です。 チェックの仕組み · 点数を上げるための改善点
- ソースリポジトリがリンクされており、アクセス可能plug-openapi/nhplug-mcp is public and reachablegithub.com/plug-openapi/nhplug-mcp ↗合格
- パッケージがこのリポジトリをソースとして指定未チェック
- ビルドの来歴 (Sigstore 証明)未チェック
- オープンソースライセンス (OSI)MITspdx.org/licenses/MIT.html ↗合格
- 過去1年以内にコミットまたはリリースありLast commit or release 2026-11-13github.com/plug-openapi/nhplug-mcp ↗合格
- OpenSSF Scorecard未チェック
- パッケージ名が有名なパッケージに酷似していない未チェック
- パッケージおよびその依存関係に重大な勧告なし未チェック
- モデルへの隠れた指示がない0 tool descriptions and the README read; no override phrases, credential paths or hidden characters合格
- 破壊的なツールがラベル付けされている未チェック
- リモートエンドポイントが MCP ハンドシェイクに応答未チェック
README
GitHubで見るNH투자증권 Open API — Local MCP Server
🏛️ NH투자증권 공식 Open API(NHPLUG) 지원 저장소입니다. · 포털 www.nhplug.com · 계정 @PLUG-OpenAPI · 문의 apisupport@nhsec.com
어떻게 쓰시겠어요?
| 하고 싶은 일 | 방법 | 시작 |
|---|---|---|
| 대화로 시세·잔고 조회 (코딩 불필요) | 이 저장소 (MCP) | Claude·ChatGPT 데스크톱 앱에 등록 (3번) |
| 내 프로그램에 넣기 (자동매매) | Python SDK | pip install nhplug |
| 예제 보며 배우기 | nhplug-sdk | git clone |
NH투자증권 Open API 를 Claude Desktop · ChatGPT 데스크톱 등 MCP 클라이언트에서 바로 사용할 수 있게 해주는 로컬 MCP 서버입니다. 국내주식(krstock)·해외주식(gbstock) 자산군의 시세·조회 API 를 AI 가 도구로 호출합니다.
- 인증 · 토큰 발급 · 헤더 ·
Input_0봉투 처리를 서버가 자동으로 대신합니다. - REST 53개 + 실시간 27채널(국내주식 34·21 / 해외주식 19·6)을 몇 개의 메타 도구로 노출해, 도구가 많아 성능이 떨어지는 문제를 피합니다.
- 🔒 조회 전용입니다 — 주문(매수·매도·정정·취소)은 실행하지 않습니다. 주문은 nhplug-sdk 코드로 합니다(6번).
현재 버전은 국내주식(krstock)·해외주식(gbstock) 자산군을 포함합니다. 다른 자산군은
specs/폴더에 openapi.json 을 추가하면 확장됩니다(맨 아래 참고).
AI·에이전트로 개발한다면
- 명세 정본 — llms.txt (N2: n2plug.com/llms.txt) · 전체 문맥은 llms-full.txt
- 개발 규칙 — nhplug-sdk/AGENTS.md (AI IDE 가 자동 로드)
- ⚠️ 호출 식별자 주의 — 이 MCP 는 operationId(
krstockQuoteCurrentPrice), Python SDK 는 URI 경로(/krstock/quote/v1/currentPrice)를 씁니다. 섞어 쓰면 동작하지 않습니다.
1. 사전 요건
- Node.js 18 이상 — nodejs.org 에서 설치. (
node -v로 확인.npx는 Node 에 포함) - NH투자증권 Open API 앱키/시크릿 — 포털 www.nhplug.com 에서 발급.
- Git — 방법 A(npx github)·방법 B(clone) 모두 필요. git-scm.com 에서 설치. (
git --version으로 확인) - API 서버 네트워크 접근 — 이 MCP 는 당신 PC 에서
*.nhplug.comAPI 서버로 직접 연결합니다. 사내망 등에서만 접근 가능한 환경이라면, MCP 를 실행하는 PC 도 그 네트워크에 있어야 합니다.
2. 설치 및 실행
방법 A — npx로 GitHub에서 바로 실행 (권장, 설치 불필요)
별도 다운로드·빌드 없이 AI 앱 설정에 한 줄이면 됩니다. 아래 command/args 를 씁니다(앱별 전체 설정은 3번).
"command": "npx",
"args": ["-y", "github:PLUG-OpenAPI/nhplug-mcp"]
첫 실행 예열(권장): npx 는 첫 실행 때 GitHub 에서 받아 빌드하느라 1분 정도 걸립니다. AI 앱이 기다리다 실패하지 않도록, 터미널에서 한 번 미리 실행해 두면 좋습니다:
npx -y github:PLUG-OpenAPI/nhplug-mcp
[nhplug-mcp] 시작됨 ...로그가 뜨면Ctrl + C로 종료. 이후 앱에서 실행이 빨라집니다.업데이트 반영: npx 는 받은 코드를 캐시합니다. 새 버전을 받으려면
npm cache clean --force후 AI 앱을 재시작하세요.
방법 B — git clone 후 로컬 빌드
git clone https://github.com/PLUG-OpenAPI/nhplug-mcp.git
cd nhplug-mcp
npm install
npm run build
빌드가 끝나면 dist/index.js 가 생성됩니다. AI 앱 설정의 실행 명령을 node, 인자를 <경로>/dist/index.js 로 등록합니다.
3. AI 앱에 연결
같은 서버·같은 키를 앱마다 등록하는 방식만 다릅니다. 쓰는 앱의 절만 보시면 됩니다.
| 앱 | 등록 방법 | 키 입력 위치 |
|---|---|---|
| Claude Desktop | 설정 파일(JSON)에 붙여넣기 | JSON 의 env |
| ChatGPT 데스크톱 | 앱 설정 화면에서 입력 | 화면의 「환경 변수」 칸 |
🔐 앱키·시크릿은 설정에만 넣으세요. 대화창에 붙여넣으면 대화 기록에 평문으로 남습니다. 두 앱 모두 설정 파일에 평문으로 저장하므로, PC 를 여러 사람이 쓴다면 주의하세요.
3-1. Claude Desktop
Claude Desktop 설정 파일 claude_desktop_config.json 을 엽니다.
- 가장 쉬운 방법: Claude Desktop → 설정(Settings) → 개발자(Developer) → Edit Config 버튼.
- 직접 열기 — Windows:
%APPDATA%\Claude\claude_desktop_config.json· macOS:~/Library/Application Support/Claude/claude_desktop_config.json⚠️ 설치 방식에 따라 실제 경로가 다를 수 있습니다. 고쳐도 반영되지 않으면 위 Edit Config 버튼으로 연 파일을 고치세요.
아래 내용을 붙여넣습니다. (방법 A · GitHub npx 기준)
{
"mcpServers": {
"nhplug": {
"command": "npx",
"args": ["-y", "github:PLUG-OpenAPI/nhplug-mcp"],
"env": {
"NHPLUG_APP_KEY": "발급받은_APP_KEY",
"NHPLUG_APP_SECRET": "발급받은_APP_SECRET",
"NHPLUG_BASE_URL": "https://api.nhplug.com:8443"
}
}
}
}
저장 후 Claude Desktop 을 완전히 종료(트레이 포함)했다가 다시 실행하면 nhplug 도구가 나타납니다.
확인: 대화창에 "삼성전자 현재가 알려줘" 라고 입력하세요. 도구 사용 허락을 묻는 창이 뜨고, 허용하면 시세가 나옵니다.
도구가 보이지 않으면 설정 → 개발자 화면에서 nhplug 서버 상태와 로그를 확인할 수 있습니다.
N2 고객은 위
env의NHPLUG_BASE_URL값을"https://api.n2plug.com:8443"으로 바꾸고,"NHPLUG_AUTH_URL": "https://api.n2plug.com:8443"한 줄을 추가하세요. (같은 이름을 두 번 쓰면 안 됩니다. 개발·검증은 BASE_URL 만moapi.n2plug.com으로, AUTH_URL 은api.n2plug.com유지)
JSON 주의: 항목 사이엔 콤마(
,), 마지막 항목 뒤엔 콤마 없음. Windows 경로의\는\\로 두 개씩. 이미 다른 서버가 있으면"nhplug": { ... }블록만mcpServers안에 추가하세요.방법 B(로컬 빌드)를 쓰면
command를"node",args를["C:\\경로\\nhplug-mcp\\dist\\index.js"]로 바꾸면 됩니다. 키는 설정의env대신 저장소 폴더의.env파일(.env.example참고)로 넣어도 됩니다.
3-2. ChatGPT 데스크톱 앱
⚠️ 데스크톱 앱에서만 됩니다. 웹(chatgpt.com)·모바일은 내 PC 에서 실행하는 MCP 를 연결할 수 없습니다. 준비물은 Claude 와 같습니다 — Node.js 18 이상(1번 사전 요건).
-
ChatGPT 데스크톱 → 설정 → 플러그인 → 상단 MCP 탭
-
오른쪽 위 추가 에서 MCP 서버를 추가하면 「맞춤형 MCP에 연결」 화면이 열립니다.
-
아래처럼 입력합니다. 인자는 한 칸에 하나씩 넣습니다(
+ 인자 추가).칸 입력 이름 nhplug유형 STDIO 실행 명령 npx인자 ① -y②github:PLUG-OpenAPI/nhplug-mcp환경 변수 (키 / 값) ① NHPLUG_APP_KEY/ 발급받은 앱키 ②NHPLUG_APP_SECRET/ 발급받은 시크릿환경 변수 패스스루 · 작업 중인 디렉토리 비워 둡니다 -
저장한 뒤 새 대화를 열고 입력창에
/mcp를 입력합니다. 목록에nhplug가 보이면 연결된 것입니다. -
"삼성전자 현재가 알려줘" 라고 물어보세요.
N2 고객은 환경 변수에
NHPLUG_BASE_URL=https://api.n2plug.com:8443,NHPLUG_AUTH_URL=https://api.n2plug.com:8443두 줄을 추가하세요.
위 화면의 내용은 %USERPROFILE%\.codex\config.toml 에 저장됩니다(macOS·Linux ~/.codex/config.toml).
Codex CLI·IDE 확장도 같은 파일을 쓰므로, 아래를 직접 넣어도 같은 결과입니다.
[mcp_servers.nhplug]
command = "npx"
args = ["-y", "github:PLUG-OpenAPI/nhplug-mcp"]
[mcp_servers.nhplug.env]
NHPLUG_APP_KEY = "발급받은_APP_KEY"
NHPLUG_APP_SECRET = "발급받은_APP_SECRET"
키를 이 파일에 남기고 싶지 않다면 「환경 변수」 대신 「환경 변수 패스스루」 칸에 이름만(NHPLUG_APP_KEY, NHPLUG_APP_SECRET) 넣고,
값은 운영체제 사용자 환경변수로 등록합니다(파일의 env_vars = ["NHPLUG_APP_KEY", "NHPLUG_APP_SECRET"] 와 같음).
Windows 는 PowerShell 에서 아래를 실행한 뒤 ChatGPT 를 완전히 종료했다가 다시 실행하세요.
[Environment]::SetEnvironmentVariable("NHPLUG_APP_KEY", "발급받은_APP_KEY", "User")
[Environment]::SetEnvironmentVariable("NHPLUG_APP_SECRET", "발급받은_APP_SECRET", "User")
4. 환경변수
| 변수 | 필수 | 설명 |
|---|---|---|
NHPLUG_APP_KEY |
✅ | 발급받은 앱키 |
NHPLUG_APP_SECRET |
✅ | 발급받은 앱시크릿 |
NHPLUG_BASE_URL |
호출 대상 REST Base URL. 기본값 https://api.nhplug.com:8443 (운영). 교육·시뮬레이션은 https://moapi.nhplug.com:8443 |
|
NHPLUG_AUTH_URL |
토큰 발급 URL. 기본 https://api.nhplug.com:8443 (운영 전용 — moapi 미제공). 보통 그대로 둡니다 |
|
NHPLUG_DEFAULT_ACCOUNT |
잔고 단축 도구에서 계좌번호 생략 시 사용 | |
NHPLUG_ALLOW_HOSTS |
사내 검증 서버 등 허용 호스트 추가(쉼표 구분). 보통 설정하지 않습니다 |
🔒
NHPLUG_BASE_URL·NHPLUG_AUTH_URL은 허용된 호스트만 통과합니다 (api/moapi×nhplug.com/n2plug.com4종). 한 글자만 틀려도 앱키·시크릿이 그대로 전송되므로, 오타가 있으면 서버가 기동하지 않고 무엇이 잘못됐는지 알려줍니다.http://(평문)와 경로가 붙은 주소도 막습니다.
접속 환경(Base URL)
| 환경 | URL |
|---|---|
| 🔴 실거래·운영 (Live) — 기본 | https://api.nhplug.com:8443 |
| 🟢 모의투자 (Mock) — 교육이수·시뮬레이션 테스트 | https://moapi.nhplug.com:8443 |
접근토큰(
/oauth2/token)은 운영(api) 전용입니다(모의투자 미제공). 호출을moapi로 하더라도 토큰은 항상api에서 발급됩니다(NHPLUG_AUTH_URL, 기본 api). 이 MCP 는 주문을 실행하지 않으므로 기본이 운영이어도 조회·시세만 수행합니다.
브랜드(도메인) — 나무(Namuh) / N2
API·필드는 동일하고 접속 도메인만 다릅니다. 위 예시는 나무(nhplug.com) 기준입니다.
| 브랜드 | 운영 | 모의투자 | 포털 |
|---|---|---|---|
| 나무(Namuh) | api.nhplug.com:8443 |
moapi.nhplug.com:8443 |
www.nhplug.com |
| N2 | api.n2plug.com:8443 |
moapi.n2plug.com:8443 |
www.n2plug.com |
⚠️ N2 고객은 설정의
NHPLUG_BASE_URL과NHPLUG_AUTH_URL을 둘 다 n2plug 로 지정하세요. AUTH_URL 까지 안 바꾸면 토큰이 나무로 가서 실패합니다.
5. 제공 도구
| 도구 | 종류 | 설명 |
|---|---|---|
list_apis |
메타 | 호출 가능한 API 목록. domain/category/keyword 필터. 여기서 operationId 를 찾습니다. |
describe_api |
메타 | 특정 operationId 의 입력 필드(Input_0) 스키마 조회. |
call_api |
메타 | operationId + 입력값으로 실제 호출. 번들에 포함된 엔드포인트 전부 커버. |
get_stock_price |
단축 | 국내주식 현재가 (종목코드만 입력). |
get_stock_balance |
단축 | 국내주식 계좌 잔고. |
list_accounts |
단축 | 보유 계좌 목록 조회 (잔고·주문 전 계좌번호 확보용, POST /n2/acctinfo). |
동작 흐름(메타 도구): list_apis 로 원하는 API 를 찾고 → describe_api 로 입력값을 확인한 뒤 → call_api 로 호출합니다. 자주 쓰는 현재가·잔고는 단축 도구로 한 번에 호출할 수 있습니다.
사용 예시 프롬프트
- "삼성전자(005930) 현재가 알려줘" →
get_stock_price - "국내주식 시세 관련 API 목록 보여줘" →
list_apis - "krstockQuoteCurrentDaily 는 어떤 입력이 필요해?" →
describe_api - "내 계좌 목록 보여줘" →
list_accounts - "내 계좌 20101234567 잔고 조회해줘" →
get_stock_balance(계좌번호는 예시)
6. 주문(거래)에 대하여 ⚠️
🔒 이 MCP 는 조회 전용입니다. 주문(매수·매도·정정·취소)은 어떤 설정으로도 실행하지 않습니다. AI 앱(Claude·ChatGPT)이나 도구 승인 설정과 무관하게 서버가 주문 호출을 거부합니다.
- 주문 API 는
list_apis목록에 나오지 않고,call_api로 부르면 거부됩니다. - 대신 주문 준비는 할 수 있습니다 —
describe_api로 주문 API 의 입력 형식을 확인하고, 시세·잔고·가능수량을 조회해 주문 파라미터를 정리하세요. - 실제 매수·매도는 코드로 실행하세요. 반드시 모의투자(
moapi) 에서 먼저 검증하세요.- 파이썬 개발·자동매매:
nhplug-sdk - 주문 API 단발 테스트(사람이 터미널에서 직접 실행, MCP 와 무관):
node scripts/order_test.mjs --account <계좌> --code 005930 --qty 1 --price 70000 --confirm
- 파이썬 개발·자동매매:
예전 버전의
NHPLUG_ENABLE_TRADING설정은 없어졌습니다. 남아 있어도 무시되며, 서버가 시작할 때 그렇게 알려줍니다.
7. 연결 검증 (self-test)
AI 앱에 붙이기 전에, API 서버 접근·인증이 정상인지 로컬에서 먼저 확인할 수 있습니다(저장소를 clone 한 경우).
# .env 에 NHPLUG_APP_KEY / NHPLUG_APP_SECRET 을 채운 뒤 (.env.example 참고)
node scripts/selftest.mjs
토큰 발급 → 삼성전자 현재가 조회까지 성공하면 전체 검증 통과 ✅ 가 출력됩니다.
8. 문제 해결
| 증상 | 원인 / 해결 |
|---|---|
환경변수 NHPLUG_APP_KEY 가 설정되지 않았습니다 |
설정의 env 또는 .env 에 키 누락 |
토큰 발급 요청 실패 (네트워크) |
API 서버에 접근 불가. 사내망/방화벽/URL 확인 |
토큰 발급 실패 (HTTP 401/403) |
앱키·시크릿 오류 또는 해당 환경 미허용 |
IGW40043 유효하지 않은 token |
캐시된 토큰 만료·무효. 자동으로 재발급 후 1회 재시도하므로 대개 그대로 성공. 반복되면 키·환경 확인 |
응답에 rsp_cd·rsp_msg 가 보임 |
정상입니다. 이 MCP 는 업무 성공/실패를 판정하지 않고 서버 응답을 그대로 전달합니다. rsp_msg 문장을 읽고 원하는 결과인지 판단하세요 — 같은 rsp_cd 가 API 마다 정상일 수도 오류일 수도 있어 코드값으로는 판정할 수 없습니다 |
[rate_limit] IGW42902 … |
호출 유량 초과(실측 초당 5회 수준). 자동 재시도하지 않습니다 — 잠시 후 다시 요청하세요 |
| Claude 에 도구가 안 보임 | 설정 저장 후 Claude Desktop 완전 종료 후 재시작. 설정 → 개발자 에서 서버 상태·로그 확인 |
ChatGPT /mcp 에 nhplug 가 없음 |
새 대화에서 다시 확인 · 인자가 한 칸에 하나씩 들어갔는지 확인 · 첫 실행은 빌드로 1분가량 걸림(2번 예열 참고) |
| 주문 API 가 목록에 없음 · 호출이 거부됨 | 의도된 동작입니다(조회 전용). 주문은 nhplug-sdk 코드로 실행하세요(6번) |
로그는 표준오류(stderr)로 출력됩니다: [nhplug-mcp] 시작됨 · baseUrl=... · 조회 전용(주문 실행 없음)
9. 자산군 확장
스펙 정본은 도메인(https://www.nhplug.com/openapi-docs/<자산>/openapi.json)입니다. 번들(specs/)은 sync:specs 로 도메인에서 당겨 최신화합니다:
npm run sync:specs # specs/ 에 이미 있는 자산 최신화
npm run sync:specs krstock gbstock # 지정 자산 받기(신규 추가)
⚠️ 커밋 전 검증 필수: 받은 뒤 MCP
call_api로 라이브 A/B(현재가·잔고)를 확인하고 커밋하세요. 도메인 재생성이 회귀할 수 있으므로, 번들은 이 검증 게이트를 거쳐 반영합니다(런타임은 항상 번들을 읽습니다).
수동으로 openapi.json 을 specs/ 에 <도메인>.openapi.json 이름으로 넣어도 됩니다. 예:
specs/
krstock.openapi.json ← 현재 포함 (국내주식)
gbstock.openapi.json ← 현재 포함 (해외주식)
krfuture.openapi.json ← 추가 시 국내파생 자동 노출
메타 도구(list_apis/describe_api/call_api)는 코드 수정 없이 새 자산군을 자동 인식합니다. (단축 도구는 자산군별로 추가 구현 가능)
저장소 구성
알고 싶은 것부터 찾아가세요. 아래는 전부 클릭되는 링크입니다.
| 파일 | 무엇이 들어 있나 |
|---|---|
src/index.ts |
MCP 서버 진입점 — 도구 등록·요청 처리 |
src/tools.ts |
제공 도구 정의(list_apis·describe_api·call_api 등) |
src/client.ts |
REST 호출 · Input_0 봉투 · 오류 메시지 추출 (업무 판정 없음 — 응답 그대로 전달) |
src/auth.ts |
토큰 발급·캐시(24h) |
src/config.ts |
환경변수 로드 · 호스트 가드(오타 차단) |
src/spec.ts |
번들 openapi.json 파싱 |
scripts/selftest.mjs |
연결 검증 |
scripts/sync_specs.mjs |
도메인에서 명세 재동기화(npm run sync:specs) |
.env.example |
설정 양식 |
specs/에는 자산군openapi.json이 번들돼 있습니다(도메인 명세의 사본). 정본은 도메인입니다 — llms.txt (N2: n2plug.com/llms.txt)
파이썬으로 개발하시려면 → nhplug-sdk · AI 개발 규칙(AGENTS.md) · 실시간 채널 27종
라이선스
MIT. 문의: apisupport@nhsec.com
NH투자증권 Open API MCPのよくある質問
このMCPで株式取引を実行できますか?
いいえ、このMCPは照会専用です。注文(買い、売り、変更、取消)を実行することはできません。取引を行うには、nhplug-sdkを使用する必要があります。
どの資産に対応していますか?
現在のバージョンでは、国内株式(krstock)および海外株式(gbstock)に対応しています。specsフォルダにopenapi.jsonを追加することで、他の資産クラスを追加できます。
接続が正常に動作しているか確認する方法はありますか?
.envファイルにAPP_KEYとAPP_SECRETを記入した後、ローカルで 'node scripts/selftest.mjs' コマンドを実行してセルフテストスクリプトを走らせることができます。