WMCA Server

NH투자증권(나무증권) WMCA DLL을 MCP(Model Context Protocol) 서버로 래핑한 프로젝트입니다.
Claude Code CLI, Claude Desktop 등 MCP를 지원하는 AI 클라이언트에서 주식 시세 조회 및 주문을 자연어로 실행할 수 있습니다.

데모

사용자: 삼성전자 현재가 알려줘
Claude: 삼성전자(005930) 현재가 73,400원, 전일 대비 +800원 (13:24 기준)

사용자: 2번째 계좌 잔고 조회해줘
Claude: 계좌 20101398553 — 예수금 33,905,892원, KG이니시스 368주 보유 중

아키텍처

[AI 클라이언트]          [mcp_server.py]             [Windows]
  Claude Code   ──────►  FastMCP (stdio)  ──────►  WmcaHandler
  Claude Desktop          MCP 도구 정의              Win32 메시지 루프
  Cursor 등               asyncio Future             wmca.dll
                          WmcaBridge                 증권사 서버

핵심 흐름:

1. AI 클라이언트가 MCP 도구 호출 (예: query_price("005930"))
2. mcp_server.py가 asyncio Future를 등록하고 WmcaHandler로 DLL 함수 호출
3. WMCA DLL이 숨겨진 Win32 윈도우로 응답 메시지 전송
4. wmca_proc.py가 메시지를 파싱하고 WmcaBridge를 통해 Future를 resolve
5. mcp_server.py가 결과를 AI 클라이언트에 반환

요구사항

• OS: Windows 전용 (Win32 API 사용)
• Python: 3.9 이상
• DLL: 아래 파일들이 프로젝트 루트에 있어야 합니다 (NH투자증권 별도 제공)
  • wmca.dll (핵심 SDK)
  • wmca.ini (서버 접속 설정)
  • libeay32.dll, librsa32.dll, nsldap32.dll
  • SKComd*.dll, SKComm*.dll, sha256w32.dll, CloudNPKI.dll

DLL 파일들은 NH투자증권 개발자 센터에서 신청 후 수령합니다.
라이선스 문제로 이 저장소에는 포함되어 있지 않습니다.

설치

# 1. 저장소 클론
git clone https://github.com/your-id/wmca-mcp.git
cd wmca-mcp

# 2. 패키지 설치
pip install -r requirements.txt

# 3. 환경변수 설정
cp .env.example .env
# .env 파일을 열어 본인의 계정 정보 입력

환경변수 설정 (.env)

WMCA_USER_ID=나무증권_아이디
WMCA_USER_PW=비밀번호
WMCA_CERT_PW=공인인증서_비밀번호

.env 파일은 .gitignore에 등록되어 있어 git에 올라가지 않습니다.
환경변수가 설정되어 있으면 서버 시작 시 자동 로그인됩니다.

실행

python mcp_server.py

MCP 클라이언트 등록

Claude Code CLI (.mcp.json)

프로젝트 루트에 .mcp.json 파일 생성:

{
  "mcpServers": {
    "wmca": {
      "type": "stdio",
      "command": "python",
      "args": ["C:/절대경로/mcp_server.py"]
    }
  }
}

MCP Inspector (테스트용)

npx @modelcontextprotocol/inspector python mcp_server.py

MCP 도구 목록

도구	설명	주요 파라미터
login	NH투자증권 서버 로그인	user_id, user_pw, cert_pw
get_accounts	로그인된 계좌 목록 조회	—
query_price	주식 현재가 조회	code (종목코드), market
query_balance	계좌 잔고 조회	acc_index (1부터), account_no, account_pwd
sell_order	매도 주문	acc_index, account_pwd, order_pwd, code, price, qty
subscribe_realtime	실시간 시세 구독 시작	code
get_realtime_data	실시간 체결 데이터 조회	code, count
get_messages	서버 수신 메시지 조회	count
disconnect	서버 연결 해제	—

acc_index는 get_accounts 반환 목록의 순서 (1번부터 시작)

파일 구조

wmca-mcp/
├── mcp_server.py      # FastMCP 서버 — MCP 도구 정의 및 진입점
├── wmca_bridge.py     # asyncio ↔ Win32 스레드 브리지 (Future 관리)
├── wmca_handler.py    # Win32 메시지 루프 및 DLL 호출
├── wmca_client.py     # ctypes DLL 로더 및 함수 시그니처 바인딩
├── wmca_proc.py       # Win32 메시지 디스패처 및 응답 파서
├── wmca_def.py        # 공통 상수 및 로그인/계좌 ctypes 구조체
├── trio_inv.py        # 시세/투자 데이터 ctypes 구조체 (현재가 등)
├── trio_ord.py        # 주문/잔고 ctypes 구조체 (잔고조회, 매도 등)
├── app.py             # PyQt5 GUI 클라이언트 (MCP 없이 직접 실행)
├── .env.example       # 환경변수 템플릿 (복사 후 .env로 사용)
├── .gitignore
├── requirements.txt
└── wmca.ini           # 서버 접속 설정 (git 제외, DLL과 함께 제공)

ctypes 구조체 규칙

새 TR을 추가할 때 참고할 규칙입니다.

• _pack_ = 1 — 1바이트 정렬 필수 (DLL 전문 규격)
• _fieldname 접미사 — 전문 구분자용 1바이트 패딩 필드
• 입력 구조체 초기화 — ctypes.memset(..., 0x20) (공백 0x20, 제로 아님)
• 문자열 인코딩 — cp949 (한국어 EUC-KR)

보안 주의사항

• .env 파일을 절대 git에 커밋하지 마세요.
• DLL 파일도 라이선스 문제로 커밋하지 마세요.
• 주문(매도/매수) 도구는 실제 거래로 이어지므로 신중하게 사용하세요.

라이선스

MIT — 단, WMCA DLL 및 관련 바이너리는 NH투자증권 라이선스를 따릅니다.