# toss-invest-mcp

토스증권 Open API(`guide.json`, OpenAPI 3.1)를 기반으로 만든 **로컬 stdio MCP 서버**입니다.
Claude Code / Claude Desktop에 붙여서 시세 조회, 계좌 조회, 주문까지 자연어로 사용할 수 있습니다.

## 제공 툴 (28개)

| 그룹 | 툴 |
|---|---|
| 시세 | `get_prices`, `get_orderbook`, `get_trades`, `get_price_limits`, `get_candles`, `get_rankings` |
| 종목/시장 정보 | `get_stocks`, `get_stock_warnings`, `get_exchange_rate`, `get_market_calendar` |
| 시장 지표 | `get_market_indicator_prices`, `get_market_indicator_candles`, `get_investor_trading` |
| 계좌/자산 | `get_accounts`, `get_holdings`, `get_buying_power`, `get_sellable_quantity`, `get_commissions` |
| 주문 ⚠️ | `list_orders`, `get_order`, `create_order`, `modify_order`, `cancel_order` |
| 조건주문 ⚠️ | `create_conditional_order`, `list_conditional_orders`, `get_conditional_order`, `modify_conditional_order`, `cancel_conditional_order` |

⚠️ 주문 관련 툴은 **실제 주문이 접수/변경/취소**됩니다.

## 설치 및 빌드

```bash
npm install
npm run build
```

## 환경변수

| 변수 | 필수 | 설명 |
|---|---|---|
| `TOSS_CLIENT_ID` | ✅ | OAuth2 클라이언트 ID |
| `TOSS_CLIENT_SECRET` | ✅ | OAuth2 클라이언트 시크릿 |
| `TOSS_ACCOUNT_SEQ` | | 계좌 툴에서 accountSeq 생략 시 사용할 기본 계좌 (`get_accounts`로 확인) |
| `TOSS_BASE_URL` | | API 베이스 URL (기본: `https://openapi.tossinvest.com`) |

액세스 토큰은 서버가 자동으로 발급·캐싱하며, 만료 60초 전 또는 401 응답 시 자동 재발급합니다.

## Claude Code 등록

이 저장소의 `.mcp.json`이 프로젝트 스코프로 서버를 등록합니다.
셸 환경에 `TOSS_CLIENT_ID` / `TOSS_CLIENT_SECRET`를 export한 뒤 이 디렉터리에서 `claude`를 실행하면 됩니다.

다른 프로젝트에서도 쓰려면 user 스코프로 등록:

```bash
claude mcp add toss-invest --scope user \
  -e TOSS_CLIENT_ID=발급받은_ID \
  -e TOSS_CLIENT_SECRET=발급받은_시크릿 \
  -- node /Users/doogi/toss-mcp/dist/index.js
```

## Claude Desktop 등록

`~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "toss-invest": {
      "command": "node",
      "args": ["/Users/doogi/toss-mcp/dist/index.js"],
      "env": {
        "TOSS_CLIENT_ID": "발급받은_ID",
        "TOSS_CLIENT_SECRET": "발급받은_시크릿"
      }
    }
  }
}
```

## 사용 예시

- "삼성전자 현재가 알려줘" → `get_prices(symbols=["005930"])`
- "코스피 거래대금 상위 10개" → `get_rankings(type=MARKET_TRADING_AMOUNT, marketCountry=KR, duration=realtime, count=10)`
- "내 보유 종목 보여줘" → `get_accounts` → `get_holdings`
- "삼성전자 10주 70,000원 지정가 매수" → `create_order(...)` ⚠️