Kiwoom API Server

키움 REST API 문서를 검색하고 조회할 수 있는 MCP (Model Context Protocol) 서버입니다.

기능

• API 검색: API ID, 이름, 카테고리 등으로 키움 REST API 검색
• API 상세 조회: 특정 API의 요청/응답 파라미터, 예제 코드 확인
• 카테고리 목록: 전체 API 카테고리 및 중분류 조회
• 요청 예제 생성: Python, JavaScript, cURL 형식의 요청 예제 코드 생성

Docker로 실행하기

1. Docker 이미지 빌드

docker build -t kiwoom-api-server:latest .

2. Docker 컨테이너 실행

docker run -d --name kiwoom-api-server \
  -p 8082:8082 \
  -e KIWOOM_DOCS_PATH=/app/kiwoom_api_docs.txt \
  -v "$(pwd)/kiwoom_api_docs.txt:/app/kiwoom_api_docs.txt:ro" \
  kiwoom-api-server:latest

3. 실행 확인

# 헬스 체크
curl http://localhost:8082/health

# 서버 정보 확인
curl http://localhost:8082/

4. 컨테이너 중지 및 삭제

# 컨테이너 중지
docker stop kiwoom-api-server

# 컨테이너 삭제
docker rm kiwoom-api-server

Docker Compose로 실행하기

저장소에 포함된 docker-compose.yml을 그대로 사용하면 현재 폴더의 kiwoom_api_docs.txt를 컨테이너에 읽기 전용으로 마운트합니다.

실행:

docker-compose up -d

환경 변수

변수명	기본값	설명
PORT	8082	서버 포트
NODE_ENV	production	실행 환경
KIWOOM_DOCS_PATH	./kiwoom_api_docs.txt	API 문서 파일 경로

엔드포인트

엔드포인트	메서드	설명
/	GET	서버 정보
/sse	GET	SSE MCP 엔드포인트
/message	POST	MCP 메시지 엔드포인트
/health	GET	헬스 체크

MCP 클라이언트 설정

VS Code Cline (WSL)

Cline MCP 설정은 프로젝트 내부 파일이 아니라 WSL 쪽 VS Code 확장 전역 설정 파일에 저장됩니다.

• 설정 파일: ~/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• 또는 Cline UI에서 MCP Servers → Configure tab → Configure MCP Servers

먼저 컨테이너를 실행한 뒤, 아래처럼 등록합니다.

{
  "mcpServers": {
    "kiwoom-api-server": {
      "timeout": 60,
      "type": "streamableHttp",
      "url": "http://127.0.0.1:8082/sse"
    }
  }
}

이 저장소 작업에서는 위 WSL 전역 설정 파일도 동일한 값으로 수정했습니다.

Claude Desktop

Claude Desktop의 설정 파일에 다음을 추가:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "kiwoom-api": {
      "url": "http://localhost:8082/sse"
    }
  }
}

다른 PC에서 접속

Docker 컨테이너가 실행 중인 PC의 IP 주소가 192.168.1.100이라면:

{
  "mcpServers": {
    "kiwoom-api": {
      "url": "http://192.168.1.100:8082/sse"
    }
  }
}

제공되는 MCP 도구

1. search_kiwoom_api: 키움 REST API 검색

   • query: 검색어 (필수)
   • category: 카테고리 필터 (선택)
   • subcategory: 중분류 필터 (선택)

2. get_kiwoom_api_detail: 특정 API 상세 정보 조회

   • api_id: API ID (예: ka10001)

3. list_kiwoom_apis: API 목록 조회

   • category: 카테고리 필터 (선택)
   • limit: 결과 개수 제한 (기본값: 50)

4. get_kiwoom_api_categories: 카테고리 목록 조회

5. get_kiwoom_request_example: 요청 예제 코드 생성

   • api_id: API ID
   • language: 프로그래밍 언어 (python, javascript, curl)

로컬 개발

# 의존성 설치
npm install

# 빌드
npm run build

# 실행
npm start

라이선스

MIT