# tossinvest-mcp

## 프로그램 개요

현재 버전: **0.3.0**

`tossinvest-mcp`는 토스증권 Open API(현재가 조회, 주문, 잔고 조회 등)를 OpenAI 서비스, Claude Desktop, Cursor 같은 MCP 지원 프로그램에서 사용할 수 있게 해주는 로컬 MCP 서버입니다.

쉽게 말해, 이 프로그램을 MCP 클라이언트에 등록하면 AI에게 다음처럼 요청할 수 있습니다.

```text
삼성전자 현재가를 조회해줘.
```

```text
내 토스증권 보유 주식을 보여줘.
```

```text
삼성전자 1주를 주문해줘.
```

**이 프로그램은 사용자의 컴퓨터에서만 실행됩니다.**

## 가장 중요한 주의사항

토스증권 Open API에는 샌드박스나 모의투자 환경이 없습니다.

거래 기능을 켜면 실제 계좌에 실제 주문을 생성, 정정, 취소할 수 있습니다. 처음 사용할 때는 반드시 거래 기능을 켜지 말고 조회 기능부터 확인하세요.

기본 설정에서는 주문 생성, 정정, 취소 도구가 등록되지 않습니다.


## 프로그램으로 할 수 있는 기능 및 특징

거래 기능을 켜지 않아도 아래 기능을 사용할 수 있습니다.

- 국내/미국 주식 현재가 조회
- 호가 조회
- 최근 체결 내역 조회
- 캔들 차트 조회
- 상한가/하한가 조회
- 종목 기본 정보 조회
- 전체 종목 목록 조회
- 매수 유의사항 조회
- 종목별 투자자·프로그램·공매도·신용거래·대차거래 동향 조회
- 주식 랭킹 조회
- 시장 지표 현재가·차트·투자자 매매동향 조회
- 섹터 목록·상세·랭킹·소속 주식·ETF 조회
- 환율 조회
- 국내/미국 장 운영 시간 조회
- 계좌 목록 조회
- 보유 주식 조회
- 매수 가능 금액 조회
- 판매 가능 수량 조회
- 매매 수수료 조회
- 주문 목록 조회
- 주문 상세 조회
- 조건주문 목록·상세 조회

거래 기능을 켠 경우 사용할 수 있는 도구:

- `toss_create_order`: 주문 생성
- `toss_modify_order`: 주문 정정
- `toss_cancel_order`: 주문 취소
- `toss_create_conditional_order`: 조건주문 생성
- `toss_modify_conditional_order`: 조건주문 수정
- `toss_cancel_conditional_order`: 조건주문 취소

0.3.0은 REST 도구 20개를 추가해 **조회 34개·거래 6개**를 제공합니다. 로컬 stdio 방식이며 WebSocket이나 원격 HTTP/SSE 서버는 제공하지 않습니다.

특징:

- `npx`로 실행되므로 별도 프로그램 설치 과정이 짧습니다.
- Client ID와 Client Secret은 환경변수로 전달합니다. 이전 이름인 API Key·Secret Key 환경변수도 호환됩니다.
- OAuth 토큰은 내부에서 자동 발급하고, 만료 60초 전에 갱신합니다. 같은 컴퓨터·OS 사용자·저장 경로에서는 여러 프로세스가 토큰과 주문 집계를 공유합니다.
- 계좌가 필요한 기능은 AI가 계좌 목록을 확인한 뒤 `accountSeq`를 입력합니다. 계좌 1을 자동 선택하지 않습니다.
- `TOSSINVEST_ACCOUNT`를 설정하면 해당 계좌로 고정하며, 다른 계좌를 지정한 호출은 거절합니다.
- 일반 주문·조건주문 생성, 정정, 취소 기능은 기본적으로 꺼져 있습니다.
- 거래 기능을 켜면 `confirmOrderAction` 없이 주문할 수 있습니다. 매도·시장가 차단 설정도 제거되었습니다.
- 1회 금액 한도, 시장별 일일 금액·건수 한도, 종목 허용목록은 필요한 항목만 환경변수로 설정할 수 있습니다. (아래 `거래 가드레일` 참고)

## 설치방법

아래 순서대로 진행하면 됩니다.

### 1. Node.js 설치 확인

터미널 또는 PowerShell을 열고 아래 명령어를 입력합니다.

```bash
node -v
```

`v20` 이상이 나오면 다음 단계로 넘어가면 됩니다.

Node.js가 없거나 버전이 낮다면 [Node.js 공식 사이트](https://nodejs.org)에서 LTS 버전을 설치한 뒤 터미널을 새로 열어 다시 확인하세요.

### 2. 토스증권 Open API 연결 정보 준비

토스증권 WTS에 로그인한 뒤 Open API 설정 화면으로 이동합니다.

그 화면에서 아래 값을 발급받아 둡니다.

- `Client ID`
- `Client Secret`

이 두 값은 MCP 설정에 넣어야 합니다. 다른 사람에게 공유하지 마세요.

### 3. 허용 IP 등록

토스증권 Open API는 허용된 IP에서만 호출할 수 있습니다. 이 설정이 빠져 있으면 `허용되지 않은 IP 주소입니다.` 같은 오류가 발생합니다.

먼저 현재 컴퓨터의 공인 IP를 확인합니다. 아래 명령어를 사용하세요.

PowerShell (Windows):

```powershell
(Invoke-WebRequest -UseBasicParsing https://api.ipify.org).Content
```

macOS 또는 Linux 터미널:

```bash
curl https://api.ipify.org
```

나온 IP 주소를 토스증권 WTS의 Open API 설정 화면에서 허용 IP 목록에 추가합니다.

대략적인 흐름:

1. 토스증권 WTS에 로그인합니다.
2. 설정 - Open API 메뉴로 이동합니다.
3. 허용 IP 관리 영역을 찾습니다.
4. 위에서 확인한 공인 IP를 추가합니다.

### 4. MCP 클라이언트에 등록

MCP 클라이언트의 설정 파일 또는 MCP Servers 설정 화면에 아래 내용을 추가합니다.

```json
{
  "mcpServers": {
    "tossinvest": {
      "command": "npx",
      "args": ["-y", "tossinvest-mcp@0.3.0"],
      "env": {
        "TOSSINVEST_CLIENT_ID": "발급받은-Client-ID",
        "TOSSINVEST_CLIENT_SECRET": "발급받은-Client-Secret"
      }
    }
  }
}
```

설정 후 MCP 클라이언트를 완전히 종료했다가 다시 실행하세요.

처음 실행할 때 npm이 지정한 버전의 `tossinvest-mcp` 패키지를 내려받습니다. 위 예시는 0.3.0을 고정해 실행합니다.

`env` 안에 연결 정보를 넣으면 별도 `.env` 파일은 필요하지 않습니다. 서버가 `.env` 파일을 자동으로 읽지는 않습니다. 다른 MCP가 이미 등록되어 있다면 기존 설정을 덮어쓰지 말고 `mcpServers` 안에 `tossinvest` 항목만 추가하세요.

### 5. 계좌 확인

처음에는 `TOSSINVEST_ACCOUNT`를 넣지 않아도 됩니다. 시세 조회에는 계좌가 필요하지 않습니다. 보유 주식이나 주문처럼 계좌가 필요한 기능에서는 AI가 계좌 목록을 확인한 뒤 `accountSeq`를 입력합니다.

MCP 클라이언트에서 다음처럼 요청합니다.

```text
토스증권 계좌 목록을 조회해줘.
```

응답의 `accountSeq`는 **실제 계좌번호가 아니라 API에서 사용하는 계좌 순번**입니다. 계좌가 하나면 AI가 선택할 수 있고, 여러 개여서 원하는 계좌를 구분하기 어려우면 사용자에게 확인하도록 도구에 안내되어 있습니다.

특정 계좌만 사용하려면 확인한 `accountSeq`를 `TOSSINVEST_ACCOUNT`에 넣습니다. 예를 들어 순번이 2인 계좌를 고정하려면 다음처럼 설정합니다.

```json
{
  "mcpServers": {
    "tossinvest": {
      "command": "npx",
      "args": ["-y", "tossinvest-mcp@0.3.0"],
      "env": {
        "TOSSINVEST_CLIENT_ID": "발급받은-Client-ID",
        "TOSSINVEST_CLIENT_SECRET": "발급받은-Client-Secret",
        "TOSSINVEST_ACCOUNT": "2"
      }
    }
  }
}
```

설정하면 계좌 관련 기능을 해당 계좌로 고정하며, 다른 `accountSeq`를 지정한 호출은 거절합니다. 미설정 시 기본 계좌는 없고, 계좌 관련 도구마다 `accountSeq`가 필요합니다.

### 6. 조회 기능 테스트

MCP 클라이언트에서 아래처럼 요청해 봅니다.

```text
삼성전자 현재가를 조회해줘.
```

```text
내 토스증권 보유 주식을 보여줘.
```

```text
AAPL 최근 체결 내역 10개를 조회해줘.
```

```text
대기 중인 주문 목록을 보여줘.
```

## 거래 기능 켜기

다시 한 번 확인하세요. 토스증권 Open API에는 샌드박스가 없습니다. 거래 기능을 켜면 실제 주문이 나갈 수 있습니다.

거래 기능을 사용하려면 MCP 설정의 `env`에 아래 값을 추가합니다.

```json
"TOSSINVEST_ENABLE_TRADING": "true"
```

전체 예시:

```json
{
  "mcpServers": {
    "tossinvest": {
      "command": "npx",
      "args": ["-y", "tossinvest-mcp@0.3.0"],
      "env": {
        "TOSSINVEST_CLIENT_ID": "발급받은-Client-ID",
        "TOSSINVEST_CLIENT_SECRET": "발급받은-Client-Secret",
        "TOSSINVEST_ACCOUNT": "2",
        "TOSSINVEST_ENABLE_TRADING": "true"
      }
    }
  }
}
```

`TOSSINVEST_ACCOUNT`의 2는 예시입니다. 계좌 목록에서 확인한 순번으로 바꾸세요. 설정 후 MCP 클라이언트를 완전히 종료했다가 다시 실행합니다.

0.3.0에서는 **`confirmOrderAction` 확인값 없이 일반 주문과 조건주문을 생성·정정·취소할 수 있습니다.** 매도와 시장가도 거래 기능을 켜면 사용할 수 있습니다. 금액·건수 한도가 필요하다면 아래 설정을 함께 넣으세요.

MCP 클라이언트에서 자연어로 요청할 때는 아래처럼 구체적으로 말하는 것이 좋습니다.

```text
토스증권에서 선택한 계좌로 삼성전자 1주를 70000원 지정가로 매수 주문해줘.
```

```text
이 주문을 71000원으로 정정해줘. 정정 후 새 주문 ID도 알려줘.
```

```text
이 주문을 취소해줘. 취소가 확인됐는지도 조회해줘.
```

### 고액 주문 확인: `confirmHighValueOrder`

`confirmHighValueOrder`는 환경변수가 아니라 주문 입력값입니다. 토스가 고액 주문 확인을 요구하면 사용자가 금액을 확인하고 승인한 경우에만 `true`로 전달해야 합니다. AI가 오류를 우회하려고 자동으로 `true`로 바꾸면 안 됩니다.

이 프로그램은 고액 여부를 별도로 판정하지 않고 토스의 오류 코드·안내를 전달합니다. 아래의 시장가 버퍼는 MCP의 주문 예산용이며 토스의 고액 주문 판정 기준과는 다릅니다.

## 거래 가드레일

가드레일은 "AI가 실수로, 또는 너무 크게/너무 자주 주문을 넣는 것"을 줄이기 위한 안전장치입니다. 설정한 한도는 주문 API를 호출하기 전에 검사합니다. 실제 체결금액·수수료·세금·손익을 관리하는 기능은 아닙니다.

옵션은 MCP 설정의 `env`에 추가합니다. **금액·건수 한도와 종목 허용목록은 기본값이 없으며, 설정한 항목만 적용됩니다.** 값은 모두 문자열로 적습니다. 예: `"TOSSINVEST_MAX_ORDER_AMOUNT_KRW": "500000"`.

### 한눈에 보기 (요약 표)

| 이름 | 기본값 | 한 줄 설명 |
| --- | --- | --- |
| `TOSSINVEST_MAX_ORDER_AMOUNT_KRW` | 없음 | 1회 주문 금액 상한(원) |
| `TOSSINVEST_MAX_ORDER_AMOUNT_USD` | 없음 | 1회 주문 금액 상한(달러) |
| `TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_KRW` | 없음 | 국내 일일 주문 금액 상한(원) |
| `TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_USD` | 없음 | 미국 일일 주문 금액 상한(달러) |
| `TOSSINVEST_DAILY_MAX_ORDER_COUNT_KRW` | 없음 | 국내 일일 생성·정정 성공 건수 상한 |
| `TOSSINVEST_DAILY_MAX_ORDER_COUNT_USD` | 없음 | 미국 일일 생성·정정 성공 건수 상한 |
| `TOSSINVEST_ALLOWED_SYMBOLS` | 없음 | 거래 가능 종목만 지정 |
| `TOSSINVEST_MARKET_ORDER_BUFFER_PCT` | `3` | 수량 시장가 주문의 예산 계산 버퍼(%) |
| `TOSSINVEST_DATA_DIR` | OS 데이터 폴더 | 토큰과 일일 집계를 공유할 디렉터리 |
| `TOSSINVEST_GUARD_STATE_PATH` | 자동 지정 | 기존 상태 파일 경로 및 새 상태 파일명 접두사 |

### 옵션별 상세 설명

#### `TOSSINVEST_MAX_ORDER_AMOUNT_KRW` / `TOSSINVEST_MAX_ORDER_AMOUNT_USD` (기본: 없음)

주문 한 건의 금액 상한입니다. KRW는 원화, USD는 달러 기준이며 **원↔달러 환산은 하지 않습니다.** 예를 들어 KRW에 `"500000"`을 설정하면 50만 원 초과 주문을 차단합니다. 양수인 금액을 넣고, 소수점도 사용할 수 있습니다.

#### `TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_KRW` / `TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_USD` (기본: 없음)

이 MCP로 접수한 주문 예산의 일일 상한입니다. 같은 범위의 매수·매도를 합산하며, 국내·미국 금액은 따로 계산합니다. 예를 들어 20달러 매수 후 20달러 매도 주문을 하면 사용액은 40달러입니다.

| 시장 | 금액·건수 초기화 시각 |
| --- | --- |
| 국내(KRW) | 매일 **KST 20:01** |
| 미국(USD) | 매일 **KST 10:01** |

자정에는 초기화하지 않습니다. 한국 시간 고정이며 서머타임·휴장일에 따라 자동 변경하지 않습니다. 예를 들어 월요일 밤의 미국 주문과 화요일 오전 10:00의 미국 주문은 같은 구간이고, 화요일 10:01부터 새 한도를 사용합니다.

#### `TOSSINVEST_DAILY_MAX_ORDER_COUNT_KRW` / `TOSSINVEST_DAILY_MAX_ORDER_COUNT_USD` (기본: 없음)

계좌별·시장별 생성·정정 성공 건수 상한입니다. 국내에 `"5"`, 미국에 `"10"`을 넣으면 각각 5건·10건으로 제한합니다. 정정도 성공할 때마다 1건으로 셉니다. 취소는 건수에 포함하지 않고 기존 건수를 돌려주지도 않습니다.

한쪽 시장의 한도를 소진해도 다른 시장에는 영향을 주지 않습니다. 한쪽만 설정하면 다른 시장은 건수 제한이 없습니다. 기존 합산 변수 `TOSSINVEST_DAILY_MAX_ORDER_COUNT`가 남아 있으면 아래 변경 사항의 호환 규칙을 확인하세요.

#### `TOSSINVEST_ALLOWED_SYMBOLS` (기본: 없음)

거래를 허용할 종목만 콤마로 나열합니다. 목록에 없는 종목의 생성·정정은 차단됩니다. 예: `"005930,AAPL,VOO"`. 국내는 6자리 숫자 코드, 미국은 티커를 씁니다. 조회 종목을 제한하는 설정은 아닙니다.

#### `TOSSINVEST_MARKET_ORDER_BUFFER_PCT` (기본: `3`)

수량 기반 시장가 주문의 예산을 계산할 때 직전 체결가(`lastPrice`)에 적용하는 비율입니다. 국내·미국 모두 같은 방식이며, 설정 범위는 `0 이상 100 미만`입니다.

| 주문 방식 | 한도 검사·집계 금액 |
| --- | --- |
| 지정가 | 수량 × 주문가격 |
| 금액 지정 시장가 | `orderAmount` |
| 수량 지정 시장가 매수 | 수량 × 직전 체결가 × `(1 + p/100)` |
| 수량 지정 시장가 매도 | 수량 × 직전 체결가 × `(1 - p/100)` |

기본 p가 3이므로 매수는 +3%, 매도는 −3%를 적용합니다. 국내 주문에 대한 토스의 상·하한가 기반 고액 판정과는 다르며, 실제 체결금액이나 접수 결과를 보장하지 않습니다. 금액 한도에 필요한 가격을 확인하지 못하면 주문을 차단하고, 금액 한도가 없으면 집계 목적만의 시세 조회는 생략합니다.

#### `TOSSINVEST_DATA_DIR` / `TOSSINVEST_GUARD_STATE_PATH`

보통 직접 지정할 필요는 없습니다. 기본 데이터 디렉터리는 다음과 같습니다.

- macOS: `~/Library/Application Support/tossinvest-mcp`
- Windows: `%LOCALAPPDATA%/tossinvest-mcp`
- Linux: `$XDG_DATA_HOME/tossinvest-mcp` 또는 `~/.local/share/tossinvest-mcp`

토큰과 주문 집계는 키별로 나누어 저장합니다. 새 주문 상태 파일은 `guard-v4-<키 식별자>.json`이며, `TOSSINVEST_GUARD_STATE_PATH`를 지정하면 그 경로에 `.v4-<키 식별자>.json`을 붙입니다.

같은 컴퓨터·OS 사용자에서 같은 키의 한도를 공유하려면 모든 MCP 프로세스에 **같은 저장 경로와 같은 한도 설정**을 사용하세요. 프로세스 간 잠금으로 토큰 발급과 주문 예산을 공유합니다. 다른 컴퓨터나 별도 저장 경로에서 같은 키로 토큰을 발급하면 기존 토큰과 충돌할 수 있습니다. Secret Key는 상태 파일에 저장하지 않습니다.

### 처음 거래를 켤 때 예시 설정

거래를 처음 켤 때는 한도를 작게 잡아 두는 것을 권장합니다. 아래는 삼성전자 주문만 허용하고 1회 30만 원·일일 100만 원·국내 생성·정정 성공 5건으로 제한한 예시입니다.

```json
{
  "mcpServers": {
    "tossinvest": {
      "command": "npx",
      "args": ["-y", "tossinvest-mcp@0.3.0"],
      "env": {
        "TOSSINVEST_CLIENT_ID": "발급받은-Client-ID",
        "TOSSINVEST_CLIENT_SECRET": "발급받은-Client-Secret",
        "TOSSINVEST_ACCOUNT": "2",
        "TOSSINVEST_ENABLE_TRADING": "true",
        "TOSSINVEST_ALLOWED_SYMBOLS": "005930",
        "TOSSINVEST_MAX_ORDER_AMOUNT_KRW": "300000",
        "TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_KRW": "1000000",
        "TOSSINVEST_DAILY_MAX_ORDER_COUNT_KRW": "5"
      }
    }
  }
}
```

`TOSSINVEST_ACCOUNT`는 계좌 목록에서 확인한 순번으로 바꾸세요. 이 예시는 **매도와 시장가를 차단하지 않습니다.** 원하는 주문 방식은 AI에게 구체적으로 지시하세요. 두 시장을 모두 거래하려면 USD 금액·건수 한도도 각각 설정합니다.

### 하루 한도 계산 방식

- **범위**: API 키·계좌·시장별로 분리하고 같은 범위의 매수·매도를 합산합니다. 토스 앱 등 다른 경로의 거래는 포함하지 않습니다.
- **신규 주문**: 접수 전에 예산을 예약하고 접수 결과를 기록합니다. 명확한 거절이면 예약을 해제하지만, 접수 여부가 불명확하면 유지합니다.
- **정정**: 기존 미체결 부분과 대체 주문금액의 차액을 반영합니다. 1회 금액 상한은 대체 주문 전체에 적용합니다.
- **취소**: 실제 취소가 확인된 미체결 부분만 차감하고 체결분은 남깁니다. 차감에는 저장한 기준가격·버퍼를 사용하며 당시 시세로 다시 평가하지 않습니다.
- **집계 구간**: 예약한 시점의 시장별 구간에 기록합니다. 응답이 초기화 이후에 도착해도 원래 구간에 반영합니다. 지난 구간의 주문을 취소해 새 구간의 사용액을 줄이지 않습니다.
- **조회 범위**: 전체 주문을 매번 재조회하지 않고 정정·취소 대상과 미확정 작업만 확인합니다. 앱에서 한 변경·자동 만료·체결가 변동은 상시 재집계하지 않습니다.
- **건수와 감소 주문**: 생성·정정 성공은 각 1건입니다. 일일 한도를 소진해도 취소나 사용액을 줄이는 정정은 허용합니다. 허용된 감액 정정도 성공 건수에는 추가됩니다.
- **조건주문**: 등록·수정 구간에 SINGLE=해당 조건, OCO=큰 조건금액, OTO=두 조건 합계로 집계합니다. 1회 한도는 각 조건에 적용합니다. 나중에 발동한 자식 주문을 다시 집계하지 않으며, 미래 발동일의 금액까지 제한하는 기능은 아닙니다.
- **취소 확인 불가**: 조건주문 취소 뒤 상세 내역이 404로 사라지면 조건별 취소·발동 여부를 추정하지 않고 예산 전액을 유지하며 경고합니다. 이미 발동한 자식 주문은 일반 주문 API로 취소해야 합니다.
- **요청 식별자**: `clientOrderId`가 없으면 자동 생성합니다. 같은 키·같은 내용의 생성 요청은 토스의 10분 멱등 기간에 중복 집계하지 않습니다. 자동 복구 재전송은 9분 이내로 제한합니다. 접수 여부가 불명확할 때 새 키로 다시 주문하지 마세요.

## 환경변수 설명

| 이름 | 필수 | 설명 |
| --- | --- | --- |
| `TOSSINVEST_CLIENT_ID` | 예 | 토스증권 Client ID. 이전 이름 `TOSSINVEST_API_KEY`도 호환 |
| `TOSSINVEST_CLIENT_SECRET` | 예 | 토스증권 Client Secret. 이전 이름 `TOSSINVEST_SECRET_KEY`도 호환 |
| `TOSSINVEST_ACCOUNT` | 아니오 | 고정할 계좌 순번. 미설정 시 계좌 관련 도구마다 `accountSeq` 입력 |
| `TOSSINVEST_BASE_URL` | 아니오 | 기본값은 `https://openapi.tossinvest.com` |
| `TOSSINVEST_ENABLE_TRADING` | 아니오 | 기본 `false`. `true`일 때 일반 주문·조건주문 생성·정정·취소 도구 등록 |

거래 가드레일과 저장 경로 관련 환경변수는 위의 `거래 가드레일` 표를 참고하세요. 전체 설정 예시는 [.env.example](.env.example)에 있습니다. 일반적인 MCP 앱 연결에서는 `.env` 파일 대신 앱의 `env` 설정에 값을 넣습니다.

## 문제 해결

### `node` 명령을 찾을 수 없다고 나옵니다

Node.js가 설치되어 있지 않거나 PATH에 등록되지 않은 상태입니다. [Node.js 공식 사이트](https://nodejs.org)에서 LTS 버전을 설치한 뒤 터미널을 새로 열고 다시 시도하세요.

### `허용되지 않은 IP 주소입니다.` 오류가 나옵니다

현재 컴퓨터의 공인 IP가 토스증권 Open API 허용 IP 목록에 등록되지 않은 상태입니다.

이 문서의 `설치방법 > 3. 허용 IP 등록` 단계를 다시 확인해 현재 공인 IP를 등록하세요. 집, 회사, 카페, VPN 등 네트워크가 바뀌면 공인 IP가 바뀔 수 있습니다.

### MCP 클라이언트에 도구가 보이지 않습니다

설정 JSON 문법이 올바른지 확인하고, MCP 클라이언트를 완전히 종료한 뒤 다시 실행하세요. Client ID와 Client Secret이 비어 있으면 서버가 시작되지 않습니다. 이 프로그램은 로컬 stdio MCP를 등록할 수 있는 앱에서 사용합니다.

### 계좌 조회는 되는데 보유 주식 조회가 실패합니다

계좌 목록에서 `accountSeq`를 확인하고 AI에게 사용할 계좌를 알려주세요. 0.3.0은 계좌 1을 자동 선택하지 않습니다. `TOSSINVEST_ACCOUNT`로 계좌를 고정한 경우에는 다른 계좌를 입력할 수 없습니다.

### 주문 도구가 보이지 않습니다

정상입니다. 기본값으로는 주문 도구가 등록되지 않습니다. 실제 거래를 허용하려면 `TOSSINVEST_ENABLE_TRADING`을 `true`로 설정하고 MCP 클라이언트를 재시작해야 합니다.

### 거래 기능을 켰는데도 주문이 안 됩니다

계좌 선택, 금액·건수 한도, 종목 허용목록과 토스가 반환한 오류를 확인하세요. `confirmOrderAction`은 제거되었으므로 입력에서 빼야 합니다. 고액 확인 오류는 사용자 승인 후 `confirmHighValueOrder`로 처리합니다.

### 주문 정정 후 기존 orderId로 조회한 내용이 이상합니다

토스증권 주문 정정은 새 `orderId`를 반환합니다. 정정 응답의 새 ID를 사용하세요. 조건주문 수정도 새 `conditionalOrderId`를 사용합니다.

### 접수 여부가 불명확하거나 미확정 작업 때문에 주문이 막힙니다

타임아웃이 났다고 주문이 거절된 것은 아닙니다. 오류의 `clientOrderId`·대상 주문 ID로 주문 목록/상세를 확인하고, 새 키로 재주문하지 마세요. 미확정 작업이 해결되기 전에는 신규·증액을 제한하며 취소 경로는 유지합니다. 상세 조회는 응답이 확인된 정정·취소의 뒤늦은 확정을 반영할 수 있고, 생성·정정을 재전송하지 않습니다.

### 하루 한도를 안 넘은 것 같은데 주문이 막힙니다

일일 금액은 매수와 매도를 합산하고 미체결 예약액도 포함합니다. 정정은 성공할 때마다 1건을 더하며, 취소해도 건수는 되돌아오지 않습니다. 국내는 KST 20:01, 미국은 KST 10:01에 초기화합니다. 가격을 확인할 수 없거나 이전 기록을 보수적으로 이월한 경우에도 차단될 수 있습니다.

### 응답에 `_guardStateWarning` 또는 `_budgetRetained`가 붙어 있습니다

접수 응답은 받았으나 한도 기록·최종 상태 확인이 끝나지 않았거나, 취소 후 내역을 확인할 수 없어 예산을 유지했다는 뜻입니다. **새 주문으로 다시 보내지 말고** 실제 주문 상태를 확인하세요. 경고가 사라졌다고 체결까지 완료됐다는 의미도 아닙니다.

### 상태 파일을 읽을 수 없다고 나옵니다

손상된 파일을 자동으로 사용액 0으로 초기화하지 않습니다. 모든 MCP 프로세스를 종료하고 파일을 백업한 뒤 원인을 확인하세요. 파일 삭제는 사용액을 잃게 하므로 한도를 푸는 방법으로 사용하지 마세요.

### 응답에 `_warnings`가 붙어 있습니다

폐기된 설정, 이전 환경변수 이름, 상태 이전 관련 안내입니다. 폐기 설정은 시작 로그와 해당 세션의 첫 도구 응답에도 알립니다. 안내에 따라 설정을 바꾼 뒤 재시작하세요. 비밀 값은 경고에 포함하지 않습니다.

## 오류 및 차단 메시지 목록

이 프로그램이 낼 수 있는 주요 메시지와 의미입니다. 주문 전 검사에서 차단된 요청은 주문 API에 전송하지 않습니다. 반면 접수 불명·접수 후 경고는 이미 전송되었을 수 있으므로 구분해야 합니다.

### 1) 주문 차단·입력 오류

| 메시지 키워드 | 의미 | 해결 방법 |
| --- | --- | --- |
| `accountSeq is required` | 사용할 계좌가 없음 | 계좌 목록을 먼저 조회한 뒤 순번 입력 |
| `Account is fixed to TOSSINVEST_ACCOUNT` | 고정 계좌와 다른 계좌 지정 | 고정 계좌 사용 또는 설정 변경 후 재시작 |
| `is not in TOSSINVEST_ALLOWED_SYMBOLS` | 허용목록 밖 종목 | 종목과 허용목록 확인 |
| `exceeds per-order limit` | 1회 금액 상한 초과 | 수량·가격·한도 확인 |
| `Daily order amount limit reached` | 해당 시장의 일일 금액 상한 도달 | 사용액 확인 후 해당 시장 초기화 시각까지 대기하거나 설정 검토 |
| `Daily order count limit reached (KRW/USD)` | 해당 시장의 일일 건수 상한 도달 | 시장별 건수와 초기화 시각 확인 |
| `KR modify requires quantity` | 국내 정정에 수량 누락 | `quantity` 입력 |
| `US modify forbids quantity` | 미국 정정에 수량 입력 | `quantity` 제외 |
| `MARKET forbids price` / `LIMIT requires price` | 주문 방식과 가격 입력 불일치 | 시장가는 가격 제외, 지정가는 가격 확인 |
| `Cannot value` / `Cannot determine currency` | 기준가격·통화 확인 불가 | 종목·가격 조회 상태 확인 |
| `unresolved prior operation` | 앞선 작업의 접수·반영이 미확정 | 해당 요청 식별자로 상태 확인, 새 키로 재주문 금지 |
| `Cannot read guard state (not reset)` | 집계 파일 손상·읽기 실패 | 프로세스 종료 후 백업·원인 확인 |

### 2) 토스 API 오류 (응답 코드/상태)

| 메시지/코드 | 의미 | 해결 방법 |
| --- | --- | --- |
| `허용되지 않은 IP 주소입니다.` | 공인 IP 미등록 | 설치 3단계대로 현재 공인 IP 등록 |
| HTTP 401 / `invalid-token` | 인증 오류 | Client ID·Client Secret과 키 활성 상태 확인. 같은 키의 별도 토큰 발급 여부 확인 |
| HTTP 429 | 요청 한도 초과 | 잠시 후 재시도. 일부 요청은 서버가 제한된 횟수로 자동 재시도 |
| `account-header-required` | 계좌 정보 필요 | `TOSSINVEST_ACCOUNT` 또는 요청의 `accountSeq` 확인 |
| `confirm-high-value-required` | 고액 주문 확인 필요 | 금액 확인·사용자 승인 후 `confirmHighValueOrder: true` 전달 |

### 3) 네트워크/연결 오류

| 메시지 | 의미 | 해결 방법 |
| --- | --- | --- |
| `Failed to connect to Toss Open API.` | 연결 실패 | 인터넷·VPN·방화벽·`TOSSINVEST_BASE_URL` 확인 |
| `Toss Open API request timed out after 20s.` | 응답 지연 | 주문 요청이었다면 실제 접수 여부부터 확인 |
| `Invalid OAuth token response` / OAuth 토큰 발급 오류 | 토큰 발급 실패 | 연결 정보·IP·키 활성 상태 확인 |

### 4) 주문 접수 후 경고·접수 불명

`_guardStateWarning`·`_budgetRetained` 또는 `Order acceptance unknown`이 보이면 실제 접수·취소 상태를 먼저 확인하세요. 한도 예산은 보수적으로 유지됩니다. 새 요청 식별자로 같은 주문을 반복하지 마세요.

## 변경 사항 (0.3.0)

### 추가된 기능

- **REST 도구 20개 추가**: 전체 종목, 종목별 매매동향 5종, 주식 랭킹, 시장 지표 3종, 섹터 5종, 조건주문 5종을 지원합니다. 조회 34개·거래 6개입니다.
- **최신 주문 입력 반영**: 국내 `timeInForce=OPG`, 시장별 주문 조합·소수점 수량·날짜·종목 개수·페이지네이션 검증을 보완했습니다.
- **일일 한도 개선**: 계좌·시장별 금액과 건수를 분리하고 국내 KST 20:01·미국 KST 10:01에 초기화합니다. 생성·정정·취소는 저장한 산정 기준으로 차액을 반영합니다.
- **공유 상태·장애 복구**: 프로세스 내부 토큰 발급을 공유하고, 같은 컴퓨터·OS 사용자·저장 경로의 프로세스 간 토큰·주문 예산 잠금을 추가했습니다. 주문 전 예산 예약과 접수 불명 작업의 식별자 보존·복구를 지원합니다.

### 수정된 동작과 호환성

| 변경 | 업데이트할 때 확인할 내용 |
| --- | --- |
| 연결 정보 이름 변경 | `TOSSINVEST_CLIENT_ID`·`TOSSINVEST_CLIENT_SECRET` 사용. 기존 `TOSSINVEST_API_KEY`·`TOSSINVEST_SECRET_KEY`도 호환하며 새 이름 우선 |
| 계좌 1 자동 선택 제거 | ACCOUNT 미설정 시 계좌 관련 도구에 `accountSeq` 입력. ACCOUNT 설정 시 해당 계좌로 고정 |
| `confirmOrderAction` 삭제 | 주문 입력에서 제거. `TOSSINVEST_REQUIRE_ORDER_CONFIRMATION`도 제거 |
| 매도·시장가 차단 설정 삭제 | `TOSSINVEST_ALLOW_SELL_ORDERS`·`TOSSINVEST_ALLOW_MARKET_ORDERS` 제거. 거래 활성화 시 매도·시장가 가능 |
| 계좌 잠금 설정 통합 | `TOSSINVEST_LOCK_ACCOUNT` 제거. ACCOUNT 설정 자체로 계좌 고정 |
| 고액 확인 인자 유지 | `confirmHighValueOrder`를 토스에 그대로 전달. 고액 여부를 로컬에서 중복 판정하거나 자동 승인하지 않음 |
| 응답 이중 래핑 수정 | `structuredContent.result.result` → `structuredContent.result`. 텍스트 JSON도 같은 구조 |
| 시장가 산정 변경 | 호가 → 직전 체결가. 버퍼 기본 5→3%, 매수 +p%·매도 −p% |
| 일일 건수 상한 분리 | `TOSSINVEST_DAILY_MAX_ORDER_COUNT_KRW`·`TOSSINVEST_DAILY_MAX_ORDER_COUNT_USD`로 각각 설정 |
| 집계 방식·파일 변경 | 시장별 초기화와 이벤트 차액 집계 사용. 기존 파일 백업 후 새 상태로 이전 |

기존 `TOSSINVEST_DAILY_MAX_ORDER_COUNT`는 호환용으로 읽지만 이제 **국내·미국 각각의 기본 상한**입니다. 기존 값이 5라면 국내 5건·미국 5건이며, 새 시장별 값이 있으면 우선합니다. 한쪽 시장을 무제한으로 쓰려면 기존 합산 변수를 제거하고 제한할 시장의 새 변수만 설정하세요.

제거된 설정은 경고 후 무시합니다. 이전 이름·폐기 설정 안내는 시작 시 `stderr`와 해당 세션의 첫 도구 응답 `_warnings`에 전달하고, 값이나 비밀정보는 출력하지 않습니다. Smithery의 기존 `apiKey`·`secretKey` 입력 필드는 유지하며 내부에서는 새 환경변수 이름을 사용합니다.

### 버그 수정·최적화

- 금액 한도가 설정된 시장에서만 가격 조회·예산 산정을 수행하도록 수정했습니다. 다른 시장의 한도 때문에 불필요하게 주문이 차단되지 않습니다.
- 공유 토큰 캐시가 null·빈 토큰 등 잘못된 형식이면 정상적으로 다시 발급하도록 보완했습니다. 고액 확인 오류 안내에도 사용자 승인 필요와 자동 확인값 변경 금지를 명시했습니다.

- 동시 요청의 토큰 중복 발급, 프로세스 간 주문 집계 덮어쓰기, 키·계좌별 집계 혼합을 수정했습니다.
- 십진수 금액 연산을 적용하고, 부분체결된 미국 주문 정정의 과대 추정과 멱등 재응답의 금액·건수 중복 집계를 수정했습니다.
- 상태 파일의 필드·금액·수량·통화를 검증합니다. 손상된 파일이나 불완전한 체결 정보를 0으로 확정하지 않습니다.
- 주문 응답 유실 시 요청 식별자를 보존하고, 접수 후 저장 실패 시 주문 성공 응답을 유지하면서 미확정 예산을 보수적으로 보존합니다.
- 불필요한 시세·전체 주문 조회, 상세 조회의 장부 쓰기 잠금, KST 날짜 포매터 재생성을 줄였습니다. 실패한 파일 교체의 임시 파일도 정리합니다.
- null·비JSON·응답 본문 수신 오류에서 원래 HTTP 상태와 요청 식별자를 보존하도록 보완했습니다.
- 조건주문 취소의 정상 `204 No Content`를 지원합니다. 취소 후 상세가 404로 사라지면 예산을 환급하지 않고 유지하며 경고합니다. 상세 조회는 생성·정정을 재전송하지 않습니다.
- SDK를 1.32.1로 올렸습니다. 개발용 UI·mock 서버·검증 스크립트·테스트 자료는 GitHub·npm 배포 대상에서 제외했고, CI는 타입 검사·빌드·패키징을 확인합니다.

### 기존 상태 파일 이전

업그레이드 전에 기존 MCP 프로세스를 모두 종료하세요. 이전 `guard-state.json`은 백업 후 현재·전일의 검증 가능한 기록을 중복 제거해 시장별 초기 사용액·건수로 한 번 가져옵니다. 이전 파일에는 API 키 식별자가 없고 미체결 단가를 완전히 복구할 수 없어, 과거 취소 환급은 추정하지 않습니다. 손상 파일을 조용히 0으로 초기화하지 않습니다.

개발 중인 0.3.0의 v3(자정 기준) 장부가 있으면 백업 후 v4로 보수적으로 이전합니다. 첫 집계 구간의 사용액이 실제보다 클 수 있습니다. 시장을 구분할 수 없는 과거 합산 건수는 각 시장 상한에 보수적으로 적용하고, 두 시장이 각각 다음 초기화 시각을 지날 때까지 유지합니다.

구버전으로 돌아갈 때는 백업 파일과 기존 설정을 사용해야 하며 새 버전에서 추가한 거래는 구버전 파일에 반영되지 않습니다. 구·신 버전을 같은 키로 동시에 실행하지 마세요.

### 업데이트 방법

npm에 새 버전이 올라와도 설치본이나 실행 중인 MCP가 자동 교체되지는 않습니다.

- **버전 고정**: 이 문서의 `tossinvest-mcp@0.3.0`은 해당 버전을 유지합니다. 업데이트하려면 버전을 직접 바꾸세요.
- **최신 버전 확인 후 실행**: `args`를 `["-y", "--prefer-online", "tossinvest-mcp@latest"]`로 설정하면 다음 실행 시 최신 태그를 확인하는 방식으로 사용할 수 있습니다.
- **전역·프로젝트 설치본**: 업데이트하거나 재설치해야 합니다. 단순한 `npx tossinvest-mcp`는 로컬 설치본·캐시·npm 설정의 영향을 받아 항상 최신이라고 보장하지 않습니다.

설정을 바꾸거나 업데이트한 뒤에는 MCP 클라이언트를 완전히 종료했다가 다시 실행하세요. 별도의 자동 업데이터는 제공하지 않습니다.

## 면책조항

이 프로그램은 토스증권 Open API를 MCP에서 사용할 수 있게 연결해 주는 도구입니다. 투자 자문, 투자 권유, 매매 추천, 수익 보장 서비스를 제공하지 않습니다.

이 프로그램을 사용해 조회한 정보, AI가 생성한 답변, AI가 제안한 주문 내용은 부정확하거나 지연되거나 사용자의 의도와 다를 수 있습니다. 모든 투자 판단과 주문 실행 및 프로그램 사용의 최종 책임은 사용자에게 있습니다.

거래 기능을 켜고 주문 생성, 정정, 취소 도구를 사용하는 경우 실제 계좌에 실제 주문이 전송될 수 있습니다. 주문 전 종목, 가격, 수량, 주문 유형, 계좌를 반드시 직접 확인하세요.

현재 이 프로젝트는 개발중인 프로젝트로서, 이 프로젝트의 개발자와 배포자는 이 프로그램 사용으로 발생하는 투자 손실, 주문 실수, API 장애, 데이터 오류, 클라이언트 오작동, AI 응답 오류 등에 대해 책임지지 않습니다.

## 라이선스

MIT License

## 기타

토스증권 Open API 공식 문서: [개발자 문서](https://developers.tossinvest.com/docs)

README.md 파일 작성 등 일부 작업에 생성형 AI의 도움을 받았음을 밝힙니다.