内容
# 📊 키움증권 개인용 MCP 서버
키움증권 REST API를 활용하여 주식 계좌 정보 및 보유 종목의 평가 현황을 조회할 수 있는 개인용 Model Context Protocol (MCP) 서버입니다.
Claude Desktop, Cursor 등 LLM 클라이언트와 연동하여 AI가 직접 투자 자산 현황을 파악하고 섹터 적합도 분석 등을 수행할 수 있도록 돕습니다.
---
## 🚀 주요 기능 (MCP 도구)
* **`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`가 방어하고 있습니다.)
