# toss-securities-mcp

토스증권 Open API를 감싸는 **self-hosted MCP 서버**입니다. 본인 API 키로 본인 머신에서 실행하고, Claude Desktop / Claude Code에 연결해 자연어로 계좌·시세를 조회할 수 있습니다.

> "삼성전자 몇 주 들고 있어?" · "지난달 체결 내역 보여줘" · "AAPL 지금 얼마야?"

## ⚠️ 디스클레이머

- 이 프로젝트는 **토스증권 공식 제품이 아닌 비공식 커뮤니티 도구**입니다.
- 사용 시 **토스증권 Open API 약관 준수 책임은 사용자 본인에게** 있습니다.
- **시세 정보는 본인 매매 목적으로만 사용 가능**합니다 (약관).
- 이 서버는 **읽기 전용 조회 도구만** 제공합니다. 주문(매수/매도) 기능은 없습니다.
- self-hosted 전용입니다. 타인에게 호스팅 서비스 형태로 제공하지 마세요.

## 제공 도구

| 도구 | 설명 |
|------|------|
| `get_account_balance()` | 계좌 잔고 요약 — 보유 주식 평가(매입/평가/손익) + 현금(KRW/USD 매수 가능 금액) |
| `get_holdings(symbol?)` | 보유 종목 — 수량, 평단가, 현재가, 평가손익 (종목 필터 가능) |
| `get_transactions(start_date, end_date, symbol?, only_filled?)` | 기간 내 체결 내역 (커서 페이징 자동 처리) |
| `get_stock_price(symbols)` | 현재가 조회 (콤마 구분, 최대 200종목) |

## 설치

요구사항: Python 3.12+, [uv](https://docs.astral.sh/uv/)

```bash
git clone <this-repo>
cd toss-securities-mcp
uv sync
```

## 설정

1. **API 키 발급** — 토스증권 WTS 로그인 → 설정 → Open API 에서 `client_id` / `client_secret` 발급
2. **환경변수 작성**

```bash
cp .env.example .env
# .env 파일에 TOSS_CLIENT_ID, TOSS_CLIENT_SECRET 입력
```

3. **accountSeq 확인 + 스모크 테스트** (실계좌 읽기 전용 조회)

```bash
uv run scripts/smoke_test.py
```

출력된 `accountSeq` 값을 `.env`의 `TOSS_ACCOUNT_SEQ`에 입력하세요.

> 🔑 `.env`는 절대 커밋하지 마세요 (`.gitignore`에 포함되어 있습니다). 키가 노출되면 즉시 토스증권에서 재발급하세요.

## Claude Desktop 연결

`claude_desktop_config.json`에 추가:

```json
{
  "mcpServers": {
    "toss-securities": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/toss-securities-mcp", "server.py"],
      "env": {
        "TOSS_CLIENT_ID": "발급받은 client_id",
        "TOSS_CLIENT_SECRET": "발급받은 client_secret",
        "TOSS_ACCOUNT_SEQ": "계좌 accountSeq"
      }
    }
  }
}
```

## Claude Code 연결

```bash
claude mcp add toss-securities \
  -e TOSS_CLIENT_ID=... -e TOSS_CLIENT_SECRET=... -e TOSS_ACCOUNT_SEQ=... \
  -- uv run --directory /absolute/path/to/toss-securities-mcp server.py
```

## 개발

```bash
uv run pytest          # 단위 테스트 (실 API 호출 없음, MockTransport)
uv run mypy            # 타입 체크 (strict)
```

- API 스펙 정본: https://openapi.tossinvest.com/openapi-docs/latest/openapi.json
- 개발 가이드: [CLAUDE.md](CLAUDE.md)

## 로드맵

이 저장소는 더 큰 시스템의 Phase 1입니다:

- **Phase 1 (이 저장소)**: 토스 MCP — 계좌·시세 조회
- **Phase 2**: portfolio-aggregator-mcp — 멀티 증권사 통합, FIFO 누적 실현손익(Lifetime Realized P/L), 행동 패턴 분석
- **Phase 4**: NH QV MCP

## 라이선스

[MIT](LICENSE)