콘텐츠로 이동

1. MCP 서버 연동 개요

STOCK-GATE는 프로그램 내부에 MCP(Model Context Protocol) 서버를 포함합니다. ChatGPT/Codex, Claude Desktop 같은 MCP 클라이언트가 STOCK-GATE에 연결되면 자연어 질문으로 시장 데이터, 관심종목, 계좌 잔고, 자동매매 설정과 계단식 트레일링 스탑 상태를 조회할 수 있습니다.

핵심 원칙 AI 클라이언트는 STOCK-GATE가 실행 중일 때만 접속할 수 있습니다. 계좌 데이터가 필요한 기능은 로그인과 잔고 조회가 완료되어야 정확한 결과를 반환합니다.

1.1 지원 범위

구분 주요 기능 예시
시장 조회 상승·하락 종목, 테마, 일봉·분봉, 보조지표 오늘 국내 상승주를 요약해줘
수급 분석 외국인·기관 일단위/분단위 추이 삼성전자 외국인 수급 흐름을 알려줘
계좌 조회 보유수량, 평균매수가, 수익률, 평가금액 내 계좌 잔고를 종목별로 요약해줘
자동매매 진단 트레일링 상태, 설정 조회, 권장값 비교 보유종목의 자동매매 설정을 진단해줘
설정 변경 보유종목 자동매매 옵션 변경 명시적 확인 후 변경 도구 사용

1.2 준비 사항

  • 최신 STOCK-GATE 프로그램과 정상 로그인 계정

  • ChatGPT 데스크톱/Codex 또는 Claude Desktop

  • Claude Desktop 연결 시 Node.js와 npx 사용 환경

  • 기본 로컬 주소 http://127.0.0.1:8766/mcp 를 사용할 수 있는 PC 환경

1.3 5분 빠른 설정

  1. STOCK-GATE의 환경설정 > General에서 MCP 서버를 활성화합니다.

  2. 포트는 기본값 8766, 원격 접속 허용은 끔 상태로 둡니다.

  3. 하단 저장을 눌러 STOCK-GATE 설정을 저장하고 프로그램을 다시 실행합니다.

  4. General 우측 MCP 클라이언트 설정에서 ChatGPT/Codex 또는 Claude 설정을 입력합니다.

  5. MCP 셋팅 파일 저장을 누른 뒤 AI 클라이언트를 완전히 종료하고 다시 실행합니다.

  6. AI에게 ‘STOCK-GATE 연결 상태를 알려줘’라고 질문해 연결을 확인합니다.

2. STOCK-GATE MCP 서버 설정

2.1 환경설정 화면 열기

STOCK-GATE에서 환경설정을 열고 General 탭으로 이동합니다. 화면은 좌측 General 설정 Grid 60%, 우측 MCP 클라이언트 설정 40%로 구성됩니다.

영역 역할
좌측 General Grid STOCK-GATE 내부 MCP 서버의 실행 주소, 포트, 인증과 원격 허용 여부 설정
우측 MCP 클라이언트 설정 ChatGPT/Codex와 Claude Desktop이 STOCK-GATE에 접속하도록 각 클라이언트 설정 파일 편집
하단 저장 좌측 STOCK-GATE 환경설정을 DB에 저장
MCP 셋팅 파일 저장 현재 선택한 우측 클라이언트 설정 파일만 즉시 저장
저장 버튼 구분 좌측 서버 설정과 우측 클라이언트 파일은 서로 다른 저장 대상입니다. 서버 설정은 하단 저장, 클라이언트 설정은 각 탭의 MCP 셋팅 파일 저장을 각각 눌러야 합니다.

2.2 MCP Server 항목

화면 항목 권장값 설명
MCP 서버 활성화 켜기 STOCK-GATE 실행 시 MCP 서버 시작
MCP 포트 8766 클라이언트 URL의 포트와 반드시 동일해야 함
MCP 바인딩 주소 빈 문자열 빈 값이면 127.0.0.1 로컬 주소로 강제
MCP 인증 토큰 선택 Bearer 인증 토큰. 공용 PC에서는 설정 권장
MCP 원격 접속 허용 끄기 기본 로컬 접속만 허용. 특별한 필요가 없으면 활성화 금지

2.3 서버 기동 확인

  1. 좌측 MCP Server 항목을 설정하고 환경설정 하단의 저장을 누릅니다.

  2. STOCK-GATE를 완전히 종료한 뒤 다시 실행합니다.

  3. 프로그램 로그에서 ‘MCP(8766) started.’ 또는 ‘bridge started at 127.0.0.1:8766’ 메시지를 확인합니다.

  4. 기동 실패 메시지가 나오면 포트 충돌, 잘못된 주소, 보안 프로그램 차단 여부를 확인합니다.

엔드포인트 클라이언트에 입력할 전체 주소는 http://127.0.0.1:8766/mcp 입니다. 마지막 /mcp 를 빠뜨리면 연결되지 않습니다.

3. ChatGPT/Codex 설정

3.1 UI를 활용한 설정 편집

MCP 설정을 설정화면을 통해서 설정 변경

3.2 설정 파일 위치

General 우측의 ChatGPT/Codex 탭은 다음 파일을 직접 편집합니다. ChatGPT 데스크톱, Codex CLI와 IDE 확장은 이 설정을 공유합니다.

Windows 설정 파일

%USERPROFILE%\.codex\config.toml

3.3 인증 토큰을 사용하지 않는 경우

로컬 PC에서만 사용하고 STOCK-GATE의 MCP 인증 토큰을 비워 둔 경우 다음 내용을 추가합니다. 기존 config.toml의 다른 설정은 삭제하지 말고 파일 끝에 추가하는 방식을 권장합니다.

config.toml 예시

[mcp_servers.stockgate]
url = "http://127.0.0.1:8766/mcp"
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 60

3.4 인증 토큰을 사용하는 경우

Codex 설정에는 토큰 원문 대신 환경변수 이름을 기록하는 것이 안전합니다. 먼저 Windows 사용자 환경변수 STOCKGATE_MCP_TOKEN에 STOCK-GATE에서 설정한 토큰과 같은 값을 등록합니다.

config.toml 인증 예시

[mcp_servers.stockgate]
url = "http://127.0.0.1:8766/mcp"
bearer_token_env_var = "STOCKGATE_MCP_TOKEN"
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 60
보안 인증 토큰을 문서, 메신저, 화면 캡처에 노출하지 마십시오. 환경변수를 새로 등록했다면 ChatGPT/Codex를 완전히 종료한 뒤 다시 실행해야 값이 반영됩니다.

3.5 저장 및 연결 확인

  1. ChatGPT/Codex 탭의 편집창에 설정을 입력합니다.

  2. MCP 셋팅 파일 저장을 누릅니다.

  3. ChatGPT 데스크톱 또는 Codex를 완전히 종료한 뒤 다시 실행합니다.

  4. MCP 서버 목록에서 stockgate가 활성 상태인지 확인합니다.

  5. ‘STOCK-GATE 앱 정보와 시장 상태를 알려줘’라고 질문합니다.

4. Claude Desktop 설정

4.1 설정 파일 위치

General 우측의 Claude Desktop 탭은 Windows의 Claude Desktop 설정 파일을 편집합니다. 파일이 없으면 기본 JSON 문서가 자동 표시됩니다.

Windows 설정 파일

%APPDATA%\Claude\claude_desktop_config.json

4.2 기본 연결 설정

Claude Desktop은 mcp-remote를 통해 STOCK-GATE의 HTTP MCP 서버에 연결할 수 있습니다. Windows에서 npx 실행 호환성을 높이기 위해 cmd /c 형태를 권장합니다.

claude_desktop_config.json 예시

{
"mcpServers": {
"stockgate": {
"command": "cmd",
"args": [
"/c",
"npx",
"-y",
"mcp-remote",
"http://127.0.0.1:8766/mcp"
]
}
}
}

4.3 인증 토큰 연결

STOCK-GATE에 MCP 인증 토큰을 설정했다면 동일한 값을 Authorization 헤더로 전달합니다. 아래 YOUR_TOKEN은 실제 토큰으로 교체합니다.

인증 토큰 포함 예시

{
"mcpServers": {
"stockgate": {
"command": "cmd",
"args": [
"/c",
"npx",
"-y",
"mcp-remote",
"http://127.0.0.1:8766/mcp",
"--header",
"Authorization: Bearer YOUR_TOKEN"
]
}
}
}
JSON 검사 Claude 탭의 저장 버튼은 JSON 문법과 최상위 객체 형식을 검사합니다. 오류가 표시되면 쉼표, 따옴표, 중괄호 위치를 먼저 확인하십시오.

4.4 저장 및 연결 확인

  1. Claude Desktop 탭에 JSON 설정을 입력합니다.

  2. MCP 셋팅 파일 저장을 누릅니다.

  3. Claude Desktop을 트레이 영역까지 완전히 종료한 뒤 다시 실행합니다.

  4. 설정 또는 개발자 메뉴의 MCP 서버 목록에서 stockgate를 확인합니다.

  5. 연결이 안 되면 명령 프롬프트에서 node --version 및 npx --version을 확인합니다.

5. AI에서 STOCK-GATE 활용하기

5.1 권장 질문 예시

목적 질문 예시 대표 도구
연결 확인 STOCK-GATE 앱 정보와 시장 상태를 알려줘
계좌 요약 내 보유종목을 수익률 높은 순으로 정리해줘
트레일링 확인 보유종목별 계단식 트레일링 상태를 설명해줘
수급 분석 005930의 최근 외국인·기관 수급 추이를 분석해줘
차트 조회 005930의 최근 일봉과 RSI를 함께 분석해줘
설정 진단 보유종목 자동매매 설정 중 위험한 값을 찾아줘
기본값 비교 내 보유종목 설정과 전역 기본값의 차이를 알려줘

5.2 제공 도구 분류

분류 도구
시장
수급
테마·차트
관심·분석
보유종목 설정
계좌
앱
분단위 수급 사용자가 ‘분단위’, ‘장중’, ‘실시간 분’처럼 명확히 요청할 때 사용하는 특수 도구입니다.

5.3 설정 변경 도구 주의

보유종목의 자동매매 설정을 변경할 수 있는 기능도 사용가능하지만, 손절률, 최저이익률, 계단 간격, 자동매매·SMS 활성, 1회 매도금액 등 실제 거래 판단에 영향을 줄 수 있으므로 주의가 필요합니다. 가급적 STOCK-GATE GUI에서 셋팅해 주세요.

거래 안전 AI의 분석과 설정 제안은 참고 정보입니다. 실제 주문과 자동매매 설정의 최종 판단 및 책임은 사용자에게 있습니다.

6. 보안 권장사항

6.1 기본 권장 구성

항목 권장값 이유
바인딩 주소 빈 값 또는 127.0.0.1 동일 PC에서만 접속 허용
원격 접속 허용 끔 외부 네트워크 노출 방지
인증 토큰 공용 PC에서 사용 승인되지 않은 로컬 프로세스 접근 방지
클라이언트 설정 사용자 계정 폴더에 저장 다른 Windows 사용자와 설정 분리
쓰기 도구 적용 전 확인 자동매매 설정의 오작동 방지

원격 접속 허용을 켜면 bindAddr에 지정한 네트워크 인터페이스로 서버가 노출될 수 있습니다. 방화벽, 사설망, VPN, 인증 토큰과 접근 통제가 준비되지 않았다면 원격 접속을 활성화하지 마십시오.

6.2 민감정보 관리

  • MCP 인증 토큰과 증권사 계정 비밀번호를 같은 값으로 사용하지 않습니다.

  • config.toml, claude_desktop_config.json을 메일이나 메신저로 공유하지 않습니다.

  • 오류 문의 시 토큰, 계좌번호, 주문번호를 가린 뒤 로그를 전달합니다.

  • 사용하지 않을 때는 MCP 서버 활성화를 끄거나 STOCK-GATE를 종료합니다.

7. 문제 해결

증상 확인 사항 조치
stockgate 서버가 안 보임 클라이언트 설정 파일 저장 여부 MCP 셋팅 파일 저장 후 클라이언트 완전 재시작
연결 거부 STOCK-GATE 실행·MCP 활성화·포트 서버를 먼저 실행하고 URL을 127.0.0.1:8766/mcp로 통일
401 Unauthorized 인증 토큰 불일치 서버 토큰과 환경변수/Authorization 헤더 값을 동일하게 수정
404 Not Found URL 경로 주소 끝에 /mcp 추가
포트 시작 실패 8766 포트 사용 프로그램 비어 있는 다른 포트로 서버와 클라이언트 설정을 함께 변경
Claude가 시작되지 않음 JSON 문법, Node.js, npx JSON 검사 후 node --version, npx --version 확인
잔고가 비어 있음 로그인 및 잔고조회 상태 증권사 로그인과 잔고 조회 완료 후 다시 요청
일부 데이터 없음 장 운영시간·캐시·지원 상태 시장 데이터 갱신 후 재요청하고 app.info로 상태 확인

8. 최종 확인 체크리스트

□ STOCK-GATE의 MCP 서버 활성화를 켰다.

□ 서버와 클라이언트의 포트가 동일하다. 기본값은 8766이다.

□ URL 끝에 /mcp가 포함되어 있다.

□ 원격 접속 허용은 특별한 사유가 없으면 꺼져 있다.

□ 인증 토큰 사용 시 서버와 클라이언트 값이 일치한다.

□ STOCK-GATE 설정은 하단 저장으로 저장했다.

□ 클라이언트 설정은 MCP 셋팅 파일 저장으로 저장했다.

□ STOCK-GATE와 AI 클라이언트를 재시작했다.

□ app.info 또는 연결 상태 질문이 정상 응답한다.

□ 설정 변경 도구는 현재값 조회와 사용자 확인 후 사용한다.

참고 문서

OpenAI MCP 문서: https://learn.chatgpt.com/docs/extend/mcp?surface=cli

Model Context Protocol 문서: https://modelcontextprotocol.io/docs/

Claude MCP 문서: https://docs.anthropic.com/en/docs/claude-code/mcp