# 📊 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**](https://github.com/astral-sh/uv): Rust 기반으로 개발된 초고속 파이썬 패키지/프로젝트 관리자
  * `mcp`: Anthropic Model Context Protocol SDK
  * `requests`: API HTTP 통신 라이브러리
  * `python-dotenv`: 로컬 환경 변수(`.env`) 로드 라이브러리

---

## 📦 설치 및 로컬 설정

### 1. `uv` 도구 설치 (Rust 기반의 초고속 패키지 매니저)
터미널(PowerShell 또는 bash)에서 아래 명령어를 실행하여 `uv`를 설치합니다.

* **Windows (PowerShell)**:
  ```powershell
  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  ```
* **macOS / Linux**:
  ```bash
  curl -LsSf https://astral.sh/uv/install.sh | sh
  ```
* **기존 pip를 사용하는 경우**:
  ```bash
  pip install uv
  ```

### 2. 가상환경 구축 및 패키지 설치
프로젝트 루트 디렉토리에서 다음 명령을 사용하여 의존성을 초고속으로 동기화합니다.
```bash
# 가상환경(.venv) 생성
uv venv

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

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

1. **환경 변수 파일 (`.env`) 생성**:
   `.env.example` 파일을 복사하여 `.env` 파일을 만들고 키움 API 인증에 필요한 AppKey 및 SecretKey를 입력합니다.
   ```bash
   cp .env.example .env
   ```
   * `KIWOOM_USE_MOCK=false`로 설정하면 실제 키움 API 서버에서 실시간 정보를 가져옵니다. `true`일 경우 내장된 모의 포트폴리오 정보를 반환합니다.

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

---

## 💻 실행 및 연동 가이드

### 1. 로컬 단독 테스트
`uv`를 통해 FastMCP 서버를 명령줄에서 직접 구동해 기동 에러가 없는지 검증합니다.
```bash
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 예시)**:
```json
{
  "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`가 방어하고 있습니다.)