📊 kiwoom-private-mcp-server

키움증권 REST API를 활용하여 주식 계좌 정보 및 보유 종목의 평가 현황을 조회할 수 있는 개인용 Model Context Protocol (MCP) 서버입니다. Claude Desktop, Cursor 등 LLM 클라이언트와 연동하여 AI가 직접 투자 자산 현황을 파악하고 섹터 적합도 분석 등을 수행할 수 있도록 돕습니다.

🚀 주요 기능 (MCP Tools)

• get_accounts: 사용자가 정의한 키움증권 계좌 목록과 각 계좌별 타겟 섹터 정보를 조회합니다.

• get_account_balance: 특정 계좌의 총 평가 자산, 개별 보유 종목의 평가 금액, 비중, 평단가 및 수익률을 조회합니다. (실제 서버 API 연동 및 모의 Mock 조회 지원)

🛠️ 요구 사항 및 기술 스택

• Python: 3.10 이상

• 의존성 도구:

  • uv: Rust 기반으로 개발된 초고속 파이썬 패키지/프로젝트 관리자

  • mcp: Anthropic Model Context Protocol SDK

  • requests: API HTTP 통신 라이브러리

  • python-dotenv: 로컬 환경 변수(.env) 로드 라이브러리

📦 설치 및 로컬 설정

1. uv 도구 설치 (Rust 기반의 초고속 패키지 매니저)

터미널(PowerShell 또는 bash)에서 아래 명령어를 실행하여 uv를 설치합니다.

• Windows (PowerShell):

  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

• macOS / Linux:

  curl -LsSf https://astral.sh/uv/install.sh | sh

• 기존 pip를 사용하는 경우:

  pip install uv

2. 가상환경 구축 및 패키지 설치

프로젝트 루트 디렉토리에서 다음 명령을 사용하여 의존성을 초고속으로 동기화합니다.

# 가상환경(.venv) 생성
uv venv

# pyproject.toml에 정의된 패키지 설치 및 로컬 프로젝트 빌드
uv pip install -e .

3. 환경 설정 파일 구성

로컬 보안 및 계좌 정보 매핑을 위해 설정 템플릿 파일들을 복사하여 실제 설정 파일을 작성합니다. (이 파일들은 .gitignore에 등록되어 깃 관리에서 배제됩니다.)

1. 환경 변수 파일 (.env) 생성: .env.example 파일을 복사하여 .env 파일을 만들고 키움 API 인증에 필요한 AppKey 및 SecretKey를 입력합니다.

   cp .env.example .env

   • KIWOOM_USE_MOCK=false로 설정하면 실제 키움 API 서버에서 실시간 정보를 가져옵니다. true일 경우 내장된 모의 포트폴리오 정보를 반환합니다.

2. 계좌 매핑 설정 파일 (accounts_config.json) 생성: accounts_config.json.example 파일을 복사하여 accounts_config.json 파일을 만들고 사용 중인 계좌 번호와 각 계좌별로 부여하고자 하는 타겟 투자 섹터명을 입력합니다.

   cp accounts_config.json.example accounts_config.json

💻 실행 및 연동 가이드

1. 로컬 단독 테스트

uv를 통해 FastMCP 서버를 명령줄에서 직접 구동해 기동 에러가 없는지 검증합니다.

uv run mcp_server.py

• 서버가 정상적으로 기동되면 mcp.server.fastmcp 엔진이 작동하며 입출력 대기 상태로 진입합니다.

2. Claude Desktop 연동 설정

Claude Desktop 앱에서 이 서버를 인식할 수 있도록 설정 파일(config.json)에 아래와 같이 추가합니다.

• 설정 파일 위치: C:\Users\<사용자명>\AppData\Roaming\EasyConnect\config.json 또는 %APPDATA%\Claude\claude_desktop_config.json

• 설정 추가 내용 (Windows 예시):

{
  "mcpServers": {
    "kiwoom-private-mcp-server": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "c:/Users/moony/home_document/kiwoom-rest-api/kiwoom-private-mcp-server",
        "mcp_server.py"
      ]
    }
  }
}

3. Cursor IDE 연동 설정

1. Cursor 설정 (Settings -> Features -> MCP)으로 이동합니다.

2. + Add New MCP Server 버튼을 누릅니다.

3. 다음과 같이 입력합니다:

   • Name: kiwoom-private-mcp-server

   • Type: command

   • Command: uv run --directory c:/Users/moony/home_document/kiwoom-rest-api/kiwoom-private-mcp-server mcp_server.py

🔒 보안 주의 사항

• 본 프로젝트는 개인 투자 계좌 및 민감한 API 인증 정보(AppKey, SecretKey)를 다룹니다.

• 절대 .env 파일과 accounts_config.json 파일을 Public GitHub 저장소에 커밋/푸시하지 않도록 각별히 유의해 주십시오. (기본적으로 .gitignore가 방어하고 있습니다.)