nhplug-mcp
OfficialThe nhplug-mcp server connects Claude Desktop and other MCP clients to the NH Investment & Securities Open API, enabling Korean stock market data retrieval and account management. It automatically handles authentication, token issuance, API headers, and request envelopes.
Core Tools
list_apis: Discover and filter 131 available NH Open API endpoints by asset class, category, or keyword.describe_api: Inspect the input schema and required parameters for any specific API endpoint.call_api: Execute any of the 131 supported endpoints byoperationId— authentication, headers, and pagination are handled automatically.get_stock_price: Retrieve the current market price of a Korean stock by its 6-digit code (e.g.,005930for Samsung Electronics).get_stock_balance: Query holdings and balance for a specified domestic stock account.list_accounts: View your registered NH accounts.
Additional Notes
Trading APIs are disabled by default — enable via
NHPLUG_ENABLE_TRADING=true. Even when enabled, AI models will not execute actual buy/sell orders due to safety policies.Currently focused on Korean domestic stocks (krstock), but extensible to other asset classes (global stocks, futures) by adding OpenAPI spec files.
Supports multiple environments: development/production mock and real trading servers via
NHPLUG_BASE_URL.Can be run via
npxdirectly from GitHub or as a local build, and integrates with Claude Desktop throughmcpServersconfiguration.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@nhplug-mcp 삼성전자 현재가 알려줘"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
NH투자증권 Open API — Local MCP Server
🏛️ NH투자증권 공식 Open API(NHPLUG) 지원 저장소입니다. · 포털 www.nhplug.com · 문의 apisupport@nhsec.com 코드로 개발·자동매매하려면 →
nhplug-sdk | 대화형 AI로 쓰려면 → 이 저장소(nhplug-mcp)
NH투자증권 Open API 를 Claude Desktop 등 MCP 클라이언트에서 바로 사용할 수 있게 해주는 로컬 MCP 서버입니다. 국내주식(krstock)·해외주식(gbstock) 자산군의 시세·조회·주문 API 를 Claude 가 도구로 호출합니다.
인증 · 토큰 발급 · 헤더 ·
Input_0봉투 처리를 서버가 자동으로 대신합니다.131개 엔드포인트를 몇 개의 메타 도구로 노출해, 도구가 많아 성능이 떨어지는 문제를 피합니다.
주문(거래) API 는 기본 비활성이며, 명시적으로 켠 경우에만 사용됩니다.
현재 버전은 국내주식(krstock)·해외주식(gbstock) 자산군을 포함합니다. 다른 자산군은
specs/폴더에 openapi.json 을 추가하면 확장됩니다(맨 아래 참고).
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 도 그 네트워크에 있어야 합니다.
Related MCP server: KIS MCP Server
2. 설치 및 실행
방법 A — npx로 GitHub에서 바로 실행 (권장, 설치 불필요)
별도 다운로드·빌드 없이 Claude 설정 한 줄이면 됩니다. 고객용 설정에 아래 command/args 를 씁니다(전체 설정은 3번).
"command": "npx",
"args": ["-y", "github:plug-support/nhplug-mcp"]첫 실행 예열(권장): npx 는 첫 실행 때 GitHub 에서 받아 빌드하느라 1분 정도 걸립니다. Claude 가 기다리다 실패하지 않도록, 터미널에서 한 번 미리 실행해 두면 좋습니다:
npx -y github:plug-support/nhplug-mcp
[nhplug-mcp] 시작됨 ...로그가 뜨면Ctrl + C로 종료. 이후 Claude 실행이 빨라집니다.업데이트 반영: npx 는 받은 코드를 캐시합니다. 새 버전을 받으려면
npm cache clean --force후 Claude 재시작.
방법 B — git clone 후 로컬 빌드
git clone https://github.com/plug-support/nhplug-mcp.git
cd nhplug-mcp
npm install
npm run build빌드가 끝나면 dist/index.js 가 생성됩니다. 이 경로를 Claude 설정에 "command": "node", "args": ["<경로>/dist/index.js"] 로 등록합니다.
3. 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
아래 내용을 붙여넣습니다. (방법 A · GitHub npx 기준)
{
"mcpServers": {
"nhplug": {
"command": "npx",
"args": ["-y", "github:plug-support/nhplug-mcp"],
"env": {
"NHPLUG_APP_KEY": "발급받은_APP_KEY",
"NHPLUG_APP_SECRET": "발급받은_APP_SECRET",
"NHPLUG_BASE_URL": "https://api.nhplug.com:8443"
}
}
}
}저장 후 Claude Desktop 을 완전히 종료(트레이 포함)했다가 다시 실행하면 nhplug 도구가 나타납니다.
N2 고객은 위
env에 두 줄을 n2plug 로 추가하세요:"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참고)로 넣어도 됩니다.
4. 환경변수
변수 | 필수 | 설명 |
| ✅ | 발급받은 앱키 |
| ✅ | 발급받은 앱시크릿 |
| 호출 대상 REST Base URL. 기본값 | |
| 토큰 발급 URL. 기본 | |
|
| |
| 잔고/주문 단축 도구에서 계좌번호 생략 시 사용 |
접속 환경(Base URL)
환경 | URL |
🔴 실거래·운영 (Live) — 기본 |
|
🟢 모의투자 (Mock) — 교육이수·시뮬레이션 테스트 |
|
접근토큰(
/oauth2/token)은 운영(api) 전용입니다(모의투자 미제공). 호출을moapi로 하더라도 토큰은 항상api에서 발급됩니다(NHPLUG_AUTH_URL, 기본 api). MCP 는 Claude 정책상 주문을 실행하지 않으므로, 기본이 운영이어도 조회·시세만 수행합니다.
브랜드(도메인) — 나무(Namuh) / N2
API·필드는 동일하고 접속 도메인만 다릅니다. 위 예시는 나무(nhplug.com) 기준입니다.
브랜드 | 운영 | 모의투자 | 포털 |
나무(Namuh) |
|
|
|
N2 |
|
|
|
⚠️ N2 고객은 설정의
NHPLUG_BASE_URL과NHPLUG_AUTH_URL을 둘 다 n2plug 로 지정하세요. AUTH_URL 까지 안 바꾸면 토큰이 나무로 가서 실패합니다.
5. 제공 도구
도구 | 종류 | 설명 |
| 메타 | 호출 가능한 API 목록. domain/category/keyword 필터. 여기서 operationId 를 찾습니다. |
| 메타 | 특정 operationId 의 입력 필드(Input_0) 스키마 조회. |
| 메타 | operationId + 입력값으로 실제 호출. 131개 엔드포인트 전부 커버. |
| 단축 | 국내주식 현재가 (종목코드만 입력). |
| 단축 | 국내주식 계좌 잔고. |
| 단축 | 보유 계좌 목록 조회 (잔고·주문 전 계좌번호 확보용, |
동작 흐름(메타 도구): list_apis 로 원하는 API 를 찾고 → describe_api 로 입력값을 확인한 뒤 → call_api 로 호출합니다. 자주 쓰는 현재가·잔고는 단축 도구로 한 번에 호출할 수 있습니다.
사용 예시 프롬프트
"삼성전자(005930) 현재가 알려줘" →
get_stock_price"국내주식 시세 관련 API 목록 보여줘" →
list_apis"krstockQuoteCurrentDaily 는 어떤 입력이 필요해?" →
describe_api"내 계좌 목록 보여줘" →
list_accounts"내 계좌 20101036881 잔고 조회해줘" →
get_stock_balance
6. 주문(거래)에 대하여 ⚠️
중요 — 대화형 AI 는 실제 주문을 대신 체결하지 않습니다. Claude 등 AI 어시스턴트는 안전정책상 사용자를 대신해 증권 주문을 실행하지 않습니다. 이는 MCP 설정(
NHPLUG_ENABLE_TRADING)이나 환경과 무관한 모델 자체의 동작이라, 서버에서 끌 수 없습니다.따라서 이 MCP 는 시세·계좌 조회, 분석, 주문 파라미터 준비까지 담당하고, 실제 매수/매도 실행은 코드로 하세요:
파이썬 개발·자동매매:
nhplug-sdk주문 API 단발 테스트(사람이 직접 실행):
node scripts/order_test.mjs --account <계좌> --code 005930 --qty 1 --price 70000 --confirm
NHPLUG_ENABLE_TRADING=true 설정은 주문 API 를 도구 목록에 노출만 합니다(설계·검증용). 실행은 위 코드 경로를 사용하세요.
기본값
false이면 주문 API 는list_apis에 표시되지 않고call_api로도 거부됩니다.주문 관련 작업은 반드시 모의투자 환경(
moapi) 에서 충분히 검증 후 진행하세요.
7. 연결 검증 (self-test)
Claude 에 붙이기 전에, API 서버 접근·인증이 정상인지 로컬에서 먼저 확인할 수 있습니다.
# .env 에 APP_KEY / APP_SECRET / BASE_URL 을 채운 뒤
node scripts/selftest.mjs토큰 발급 → 삼성전자 현재가 조회까지 성공하면 전체 검증 통과 ✅ 가 출력됩니다.
8. 문제 해결
증상 | 원인 / 해결 |
| 설정의 |
| API 서버에 접근 불가. 사내망/방화벽/URL 확인 |
| 앱키·시크릿 오류 또는 해당 환경 미허용 |
| 캐시된 토큰 만료·무효. 자동으로 재발급 후 1회 재시도하므로 대개 그대로 성공. 반복되면 키·환경 확인 |
| HTTP 는 200 이지만 업무 오류입니다. |
| 호출 유량 초과(실측 초당 5회 수준). 자동 재시도하지 않습니다 — 잠시 후 다시 요청하세요 |
Claude 에 도구가 안 보임 | 설정 저장 후 Claude Desktop 완전 종료 후 재시작 |
주문 도구가 안 보임 | 의도된 동작. |
로그는 표준오류(stderr)로 출력됩니다: [nhplug-mcp] 시작됨 · baseUrl=... · trading=...
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)는 코드 수정 없이 새 자산군을 자동 인식합니다. (단축 도구는 자산군별로 추가 구현 가능)
라이선스
MIT. 문의: apisupport@nhsec.com
Available Tools
5 toolscall_apiA
operationId 와 입력값으로 NH Open API 를 실제 호출합니다. 인증/헤더/Input_0 봉투는 자동 처리됩니다. 주문(거래) API 는 서버가 거래 활성화 모드(NHPLUG_ENABLE_TRADING=true)일 때만 호출됩니다.
Inputs: input (required), operationId (required), cts.
describe_apiA
특정 operationId 의 입력 필드(Input_0) 스키마를 반환합니다. call_api 호출 전에 어떤 파라미터가 필요한지 확인하는 용도입니다.
Inputs: operationId (required).
get_stock_balanceA
국내주식 계좌 잔고를 조회합니다. (단축 도구 = krstockInquiryBalance)
Inputs: account_no.
get_stock_priceA
국내주식 현재가 시세를 조회합니다. (단축 도구 = call_api 로 krstockQuoteCurrentPrice 를 호출하는 것과 동일)
Inputs: stock_code (required).
list_apisA
NH투자증권 Open API 에서 호출 가능한 엔드포인트 목록을 조회합니다. 자산군(domain)·카테고리·키워드로 필터링할 수 있습니다. 먼저 이 도구로 원하는 API 의 operationId 를 찾은 뒤 describe_api / call_api 로 이어가세요. 주문(거래) API 는 서버가 거래 활성화 모드일 때만 표시됩니다.
Inputs: domain, keyword, category.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose: list_apis for discovery, describe_api for schema, call_api for execution, and get_stock_balance/price for common queries. No ambiguity.
Mostly consistent verb_noun pattern (call_api, describe_api, list_apis) but stock shortcuts use 'get_stock_' prefix, which is a minor deviation. Overall readable and predictable.
Five tools is well-scoped for a financial API wrapper: listing, schema, generic call, plus two convenience shortcuts. Not excessive or insufficient.
Covers the full workflow: discover APIs (list_apis), inspect input schema (describe_api), execute any API (call_api), and provides shortcuts for common balance and price queries. No dead ends.
Related MCP Connectors
Korean company facts in English for AI agents: ~830 KOSPI-listed companies (DART profiles, KRW financials, recent filings) and ~110,000 corporate public procurement suppliers (12-month KONEPS contract awards), plus live National Tax Service business status checks. 4 tools, keyless, read-only.
Trade Robinhood through natural language in Claude Code.
Your investing research inside Claude: watchlists, financial ratios, reverse-DCF valuations, investment theses, notes, portfolio, earnings calendar and news for the companies you follow. 70 read and write tools; ask what's on your morning desk, rank a watchlist by ROE, log a trade or save a thesis. OAuth sign-in. Free to start.
Connect brokerage accounts to AI assistants: holdings, orders, asset lookup, and approved trading.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables interaction with the Korea Investment & Securities (KIS) Open API for domestic and overseas stock trading, real-time market data, and automated strategy execution. It provides a structured interface for LLMs to perform trading operations, manage portfolios, and conduct backtesting.-
- FlicenseAqualityCmaintenanceEnables Claude to trade Korean and overseas stocks, check balances, and search stock information through the Korea Investment & Securities Open API.12-
- AlicenseNot gradedqualityBmaintenanceEnables querying Korean and US stock information, quotes, account assets, and order history via Toss Securities Open API. Optionally supports order placement with preview and confirmation safeguards.1MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI clients like Claude Code to perform stock price queries and trading orders through NH투자증권's WMCA DLL using natural language.-