# Korean Finance MCP Server

Claude Desktop과 연동하는 MCP 서버입니다.  
키움증권(주식/채권), KRX(장내채권), 국토부(아파트 실거래가), 한국은행 ECOS(기준금리/환율/물가) 데이터를 제공합니다.

## 제공 툴 (13개)

### 키움증권
| 툴 | 설명 |
|---|---|
| `get_stock_price` | 주식 현재가 조회 |
| `get_stock_daily_chart` | 일봉 차트 (count 지정 가능) |
| `get_stock_minute_chart` | 분봉 차트 (1/3/5/10/15/30/60분) |
| `get_portfolio` | 보유 종목 조회 |
| `search_otc_bond` | 키움 장외채권 상품 검색 |

### KRX 장내채권
| 툴 | 설명 |
|---|---|
| `search_bond` | 채권명으로 장내채권 종목 검색 |
| `get_bond_price` | 장내채권 현재 시세 (종가·수익률·전일대비) |

### 국토부 실거래가
| 툴 | 설명 |
|---|---|
| `search_region_code` | 지역명 → 법정동 코드 검색 |
| `get_apt_trade` | 아파트 매매 실거래가 |
| `get_apt_rent` | 아파트 전월세 실거래가 |

### 한국은행 ECOS
| 툴 | 설명 |
|---|---|
| `get_base_rate` | 기준금리 추이 |
| `get_exchange_rate` | 환율 (USD/JPY/EUR/CNY) |
| `get_inflation` | 소비자물가지수(CPI) |

## API 키 발급

| 서비스 | 발급 링크 | 환경변수 |
|---|---|---|
| 키움증권 Open API | https://apiportal.kiwoom.com | `KIWOOM_APP_KEY`, `KIWOOM_APP_SECRET` |
| 공공데이터 포털 | https://www.data.go.kr | `DATA_GO_API_KEY` |
| 한국은행 ECOS | https://ecos.bok.or.kr/api/#/DevGuide/APIKeyRequest | `ECOS_API_KEY` |
| KRX 정보데이터시스템 | https://data.krx.co.kr (인증 불필요) | — |

## 설치

```bash
pip install -e .
```

## Claude Desktop 연동

`claude_desktop_config.json` 파일을 아래와 같이 설정합니다.

**파일 위치:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "korean-finance": {
      "command": "python",
      "args": ["-m", "kiwoom_mcp.server"],
      "env": {
        "KIWOOM_APP_KEY": "여기에_키움_앱키_입력",
        "KIWOOM_APP_SECRET": "여기에_키움_앱시크릿_입력",
        "KIWOOM_ACCOUNT_NO": "여기에_계좌번호_입력",
        "DATA_GO_API_KEY": "여기에_공공데이터_API키_입력",
        "ECOS_API_KEY": "여기에_한국은행_ECOS키_입력",
        "KRX_API_KEY": "여기에_KRX_API키_입력"
      }
    }
  }
}
```

> `"command"` 경로는 `kiwoom-mcp`를 설치한 Python 환경의 실행 파일이어야 합니다.  
> 가상환경을 사용하는 경우 절대 경로 사용 권장:  
> - Windows: `"C:\\Users\\사용자이름\\venv\\Scripts\\python.exe"`  
> - macOS/Linux: `"/Users/사용자이름/venv/bin/python"`

## 사용 예시

Claude에게 자연어로 질문하세요:

- "삼성전자 현재 주가 알려줘" → `get_stock_price(stock_code="005930")`
- "강남구 2025년 3월 아파트 실거래가 보여줘" → `search_region_code` → `get_apt_trade`
- "최근 1년 기준금리 추이 보여줘" → `get_base_rate(count=12)`
- "국고채 3년 현재 시세 알려줘" → `search_bond(bond_name="국고")` → `get_bond_price`
- "키움에서 파는 장외채권 알려줘" → `search_otc_bond(bond_type="국채")`