TossInvest MCP

English

토스증권 공식 Open API를 Hermes Agent 같은 MCP 클라이언트에서 사용할 수 있도록 만든 오픈소스 MCP 서버입니다.

국내·미국 주식의 종목 정보와 시세, 계좌 자산, 주문 내역을 조회할 수 있습니다. 주문 기능은 기본적으로 꺼져 있으며, 별도로 활성화한 경우에도 미리보기와 일회용 확인 절차를 통과해야 주문 생성·정정·취소가 실행됩니다.

이 프로젝트는 토스증권의 공식 제품이 아닌 독립 오픈소스 프로젝트입니다. 투자 조언을 제공하지 않으며, 이 서버를 통해 실행한 주문과 그 결과에 대한 책임은 사용자에게 있습니다.

목차

• 주요 특징

• 동작 구조

• 빠른 시작

• 토스증권 API 인증 정보 준비

• 환경변수 설정

• Docker로 실행

• Hermes Agent 연결

• Hermes Skill 설치

• 제공 도구

• 주문 기능 활성화

• 주문 안전장치

• 응답과 오류 형식

• 운영과 보안

• 로컬 개발

• 문제 해결

• 현재 제한사항

Related MCP server: KIS MCP Server

주요 특징

• 토스증권 Open API v1.1.1의 모든 조회 operation 지원

• OAuth 2.0 Client Credentials 토큰 자동 발급 및 메모리 캐시

• 토큰 만료 60초 전 선제 갱신과 동시 갱신 방지

• 공식 API 그룹별 로컬 rate limit 적용

• 조회 요청의 429 Too Many Requests만 제한적으로 재시도

• 주문 생성·정정·취소 요청은 어떤 경우에도 자동 재시도하지 않음

• 계좌번호와 account sequence를 MCP 응답에서 제거

• 기본 조회 전용 모드

• 주문 생성·정정·취소의 미리보기 → 명시적 확인 → 실행 흐름

• 2분 후 만료되는 일회용 주문 확인 정보

• 원화·달러 주문 한도와 1억원 이상 주문의 강제 차단

• 국내 시장가 주문을 현재가가 아닌 공식 상한가 기준으로 보수적으로 검사

• 매수 가능 금액과 판매 가능 수량을 주문 미리보기 단계에서 검증

• Bearer 인증과 Origin 검사가 적용된 Streamable HTTP MCP

• non-root, read-only filesystem, capability 제거가 적용된 Docker 구성

• Hermes Agent 설정 예제 및 거래 안전 절차를 담은 Skill 제공

동작 구조

flowchart LR
    U["사용자"] --> H["Hermes Agent"]
    H -->|"MCP Streamable HTTP<br/>Bearer 인증"| M["TossInvest MCP"]
    M --> A["OAuth 토큰 캐시"]
    M --> R["Rate Limiter"]
    M --> S["주문 안전장치"]
    A --> T["토스증권 Open API"]
    R --> T
    S --> T

TossInvest MCP는 토스증권 인증 정보를 Hermes에 전달하지 않습니다. 서버가 내부적으로 OAuth 토큰을 발급하고, Hermes에는 필요한 MCP 도구와 정제된 결과만 노출합니다.

기본 실행 주소:

빠른 시작

준비물

• 토스증권 Open API client_id, client_secret

• Docker 및 Docker Compose

• Hermes Agent

• 설정 파일을 편집할 수 있는 기본적인 터미널 환경

1. 저장소 받기

git clone https://github.com/cha2hyun/tossinvest-mcp.git
cd tossinvest-mcp

2. 환경변수 파일 만들기

cp .env.example .env
openssl rand -hex 32

openssl이 출력한 임의 문자열은 .env의 MCP_AUTH_TOKEN에 넣습니다.

최소 설정 예시:

TOSSINVEST_CLIENT_ID=발급받은_client_id
TOSSINVEST_CLIENT_SECRET=발급받은_client_secret
TOSSINVEST_ACCOUNT_SEQ=1
TOSSINVEST_ENABLE_TRADING=false

MCP_AUTH_TOKEN=openssl로_생성한_충분히_긴_임의_문자열
MCP_PUBLISHED_PORT=8000
LOG_LEVEL=INFO

TOSSINVEST_ACCOUNT_SEQ의 실제 값은 계좌마다 다를 수 있습니다. 확인 방법은 계좌 sequence 확인을 참고하세요.

3. 서버 실행

docker compose up -d --build

4. 상태 확인

curl http://127.0.0.1:8000/healthz
curl http://127.0.0.1:8000/readyz
docker compose ps
docker compose logs -f tossinvest-mcp

정상 상태 예시:

{"status":"ok","service":"tossinvest-mcp"}

readyz는 토스증권 OAuth 토큰 발급까지 확인하므로 인증 정보가 잘못된 경우 503을 반환합니다.

토스증권 API 인증 정보 준비

1. 토스증권 WTS에 로그인합니다.

2. 설정의 Open API 메뉴에서 API 클라이언트를 등록합니다.

3. 발급된 client_id와 client_secret을 안전하게 보관합니다.

4. 두 값은 TossInvest MCP 서버의 .env에만 저장합니다.

client_secret은 Git 저장소, Hermes 설정, 프롬프트, 채팅, 로그에 넣으면 안 됩니다.

계좌 sequence 확인

계좌·자산·주문 API는 X-Tossinvest-Account 헤더에 accountSeq가 필요합니다. 이 값은 계좌번호가 아니며, 토스증권의 계좌 목록 API에서 확인합니다.

jq가 설치된 로컬 터미널에서 다음처럼 조회할 수 있습니다.

set -a
source .env
set +a

ACCESS_TOKEN="$(
  curl -fsS -X POST 'https://openapi.tossinvest.com/oauth2/token' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode "client_id=${TOSSINVEST_CLIENT_ID}" \
    --data-urlencode "client_secret=${TOSSINVEST_CLIENT_SECRET}" |
  jq -r '.access_token'
)"

curl -fsS 'https://openapi.tossinvest.com/api/v1/accounts' \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" |
jq '.result[] | {accountSeq, accountType}'

unset ACCESS_TOKEN

출력된 accountSeq를 .env의 TOSSINVEST_ACCOUNT_SEQ에 설정합니다. 위 명령은 계좌 식별 정보를 다루므로 출력 내용을 공유하거나 저장소에 남기지 마세요.

MCP의 list_accounts 도구는 보안을 위해 원본 계좌번호와 accountSeq를 반환하지 않습니다. 계좌 유형과 현재 서버에 설정된 계좌인지 여부만 제공합니다.

환경변수 설정

주의사항:

• .env는 .gitignore에 포함되어 있지만 별도로 백업·공유하지 않는 것이 안전합니다.

• MCP_AUTH_TOKEN은 토스증권 client_secret과 다른 값이어야 합니다.

• 주문 기능을 켜면 계좌 sequence와 두 통화의 주문 한도가 모두 필요합니다.

• 빈 주문 한도는 무제한을 의미하지 않습니다. 주문 활성화 시 서버 시작 실패로 처리됩니다.

Docker로 실행

빌드와 시작

docker compose up -d --build

로그 확인

docker compose logs -f tossinvest-mcp

재시작

docker compose restart tossinvest-mcp

종료

docker compose down

다른 호스트 포트 사용

.env:

MCP_PUBLISHED_PORT=18000

이 경우 MCP 주소는 http://127.0.0.1:18000/mcp가 됩니다. Hermes 설정의 URL도 같은 포트로 수정해야 합니다.

Compose는 기본적으로 포트를 127.0.0.1에만 바인딩합니다. 같은 컴퓨터에서 실행되는 Hermes만 접근할 수 있는 구성이며, 특별한 이유 없이 0.0.0.0으로 공개하지 마세요.

공개 이미지 사용

릴리스 태그가 발행된 이후에는 GHCR 이미지를 사용할 수 있습니다.

docker pull ghcr.io/cha2hyun/tossinvest-mcp:latest
docker compose up -d

특정 버전을 운영 환경에 고정하려면 latest 대신 SemVer 태그를 사용하는 것을 권장합니다.

Hermes Agent 연결

1. Hermes용 토큰 저장

~/.hermes/.env:

TOSSINVEST_MCP_AUTH_TOKEN=.env의_MCP_AUTH_TOKEN과_동일한_값

Bearer 접두사는 이 파일에 넣지 않습니다.

2. MCP 서버 설정 추가

~/.hermes/config.yaml의 최상위 mcp_servers 아래에 추가합니다.

mcp_servers:
  tossinvest:
    url: "http://127.0.0.1:8000/mcp"
    headers:
      Authorization: "Bearer ${TOSSINVEST_MCP_AUTH_TOKEN}"
    enabled: true
    timeout: 120
    connect_timeout: 30
    supports_parallel_tool_calls: false
    tools:
      include:
        - get_stock_info
        - get_stock_warnings
        - get_prices
        - get_orderbook
        - get_recent_trades
        - get_price_limits
        - get_candles
        - get_exchange_rate
        - get_market_calendar
        - list_accounts
        - get_holdings
        - list_orders
        - get_order
        - get_buying_power
        - get_sellable_quantity
        - get_commissions
      resources: false
      prompts: false

동일한 예제는 examples/hermes-config.yaml에도 있습니다.

3. 연결 확인

hermes mcp test tossinvest

조회 전용 기본 모드에서는 16개 도구가 보여야 하며, place_order, modify_order, cancel_order 같은 주문 실행 도구는 보이면 안 됩니다.

Hermes Skill 설치

MCP 도구는 “무엇을 실행할 수 있는지”를 제공하고, Skill은 Hermes에 “어떤 순서와 안전 규칙으로 사용해야 하는지”를 알려줍니다.

mkdir -p ~/.hermes/skills/tossinvest
cp skills/tossinvest/SKILL.md ~/.hermes/skills/tossinvest/SKILL.md
hermes skills list | grep tossinvest

설치 후 새 Hermes 세션을 시작합니다. Skill은 다음 흐름을 안내합니다.

1. 종목과 시장 확인

2. 장 운영 시간 확인

3. 종목 경고 조회

4. 매수 가능 금액 또는 판매 가능 수량 확인

5. 주문 미리보기

6. 사용자에게 정확한 주문 내용 제시

7. 명시적 확인 후 한 번만 주문 실행

8. 주문 상세 재조회

9. 상태가 불명확하면 재주문하지 않고 주문 내역 확인

Skill은 행동 지침이며 보안 경계가 아닙니다. 거래 제한과 확인 절차는 MCP 서버도 독립적으로 강제합니다.

제공 도구

Hermes에서는 서버 이름이 도구명 앞에 붙어 mcp_tossinvest_get_prices처럼 보일 수 있습니다. 아래 표는 MCP 서버 내부 도구명을 기준으로 합니다.

종목·시세

여러 종목을 받는 symbols 입력은 쉼표로 구분합니다.

005930,000660,AAPL

시장 정보

계좌·자산

주문 조회

주문 실행

다음 도구는 TOSSINVEST_ENABLE_TRADING=true일 때만 등록됩니다.

주문 기능 활성화

먼저 충분히 낮은 주문 한도로 시작하세요.

.env:

TOSSINVEST_ACCOUNT_SEQ=1
TOSSINVEST_ENABLE_TRADING=true
TOSSINVEST_MAX_ORDER_KRW=1000000
TOSSINVEST_MAX_ORDER_USD=500

설정을 변경한 뒤 컨테이너를 다시 생성합니다.

docker compose up -d --build --force-recreate

Hermes allowlist에도 주문 도구를 명시적으로 추가해야 합니다.

tools:
  include:
    # 기존 조회 도구
    - preview_order
    - place_order
    - preview_order_modification
    - modify_order
    - preview_order_cancellation
    - cancel_order

거래 활성화 모드에서는 총 22개 도구가 등록됩니다.

주문 안전장치

1. 거래 도구 기본 비노출

TOSSINVEST_ENABLE_TRADING=false이면 주문 도구는 실행 실패 상태로 남는 것이 아니라 MCP 도구 목록 자체에 등록되지 않습니다.

2. 미리보기와 일회용 확인

주문을 바로 실행할 수 없습니다. 먼저 미리보기 도구를 호출해야 합니다.

미리보기는 다음 정보를 반환합니다.

• preview_id

• 2분간 유효한 정확한 확인 문구

• 종목, 방향, 가격, 수량 또는 금액

• 현재가와 예상 주문 금액

• 원화 환산 예상 금액

• 종목 경고와 장 운영 정보

• 매수 가능 금액 또는 판매 가능 수량

실행 도구는 같은 preview_id와 정확한 확인 문구를 요구합니다. 확인 정보는 한 번 사용하면 폐기되며, 2분이 지나거나 서버가 재시작되면 새 미리보기가 필요합니다.

3. 주문 금액 제한

• TOSSINVEST_MAX_ORDER_KRW

• TOSSINVEST_MAX_ORDER_USD

• 원화 환산 1억원 이상 주문의 강제 차단

미국 주문은 공식 환율로 원화 가치를 계산하여 1억원 제한도 함께 검사합니다.

4. 시장가 주문의 보수적 검사

국내 시장가 주문은 현재가가 아닌 공식 상한가를 기준으로 예상 금액과 매수 가능 금액을 검사합니다. 실제 주문 시점의 가격 변동으로 설정 한도를 넘어갈 가능성을 줄이기 위한 정책입니다.

5. 주문 자동 재시도 금지

주문 생성·정정·취소는 토큰 만료 응답, rate limit, timeout, 네트워크 오류가 발생해도 자동으로 재전송하지 않습니다.

전송 이후 연결이 끊겨 주문 성공 여부를 알 수 없으면 다음 오류를 반환합니다.

order-state-unknown

이 경우 같은 주문을 다시 실행하지 말고 list_orders와 get_order로 상태부터 확인해야 합니다.

6. 멱등성

주문 생성 시 서버가 clientOrderId를 자동 생성합니다. 토스증권은 이 값을 기준으로 10분간 멱등성을 제공합니다. 다만 이 기능을 믿고 애플리케이션이 주문을 자동 재시도하지는 않습니다.

응답과 오류 형식

정상적인 Toss API 결과는 다음 형태로 정규화됩니다.

{
  "data": {},
  "meta": {
    "request_id": "토스증권 요청 식별자",
    "retrieved_at": "2026-06-18T04:00:00+00:00",
    "rate_limit": {
      "limit": "10",
      "remaining": "9",
      "reset": "0.1"
    }
  }
}

request_id는 토스증권 문의나 장애 추적 시 유용합니다.

예상 가능한 오류는 MCP ToolError 안에 다음 정보가 포함됩니다.

{
  "error": {
    "status_code": 429,
    "code": "rate-limit-exceeded",
    "message": "요청 한도를 초과했습니다.",
    "request_id": "request-id",
    "data": null
  }
}

토스증권 Authorization header, OAuth access token, client secret, account sequence는 결과나 로그에 노출하지 않습니다.

운영과 보안

기본 Compose 보안 설정:

• 호스트의 127.0.0.1에만 포트 공개

• 컨테이너 non-root 사용자 실행

• read-only root filesystem

• Linux capability 전체 제거

• no-new-privileges

• /tmp만 제한된 임시 filesystem으로 제공

• healthcheck와 자동 재시작

• Uvicorn 단일 worker

외부 서버에 배포할 때

이 저장소의 Compose 포트를 그대로 인터넷에 공개하면 안 됩니다.

• HTTPS reverse proxy 사용

• MCP streaming 응답을 buffering하지 않도록 설정

• 방화벽 또는 사설망으로 접근 제한

• 충분히 긴 MCP_AUTH_TOKEN 사용

• secret manager 사용

• /healthz, /readyz의 외부 접근 제한

• Hermes allowlist 최소화

• 주문 한도를 낮게 시작

자세한 내용은 SECURITY.md를 참고하세요.

로컬 개발

Python 3.12와 uv가 필요합니다.

uv sync --all-extras

서버 직접 실행:

cp .env.example .env
uv run tossinvest-mcp

검증:

uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pip-audit --strict
uv run python scripts/update_openapi.py --check
docker build .

공식 OpenAPI 검사기는 다음을 확인합니다.

• API 버전

• 전체 OpenAPI 문서의 SHA-256 fingerprint

• 모든 HTTP operation

• 공식 operationId와 MCP 구현의 매핑

공식 스키마 변경을 검토한 뒤 manifest를 갱신하려면:

uv run python scripts/update_openapi.py --update

문제 해결

401 Unauthorized

MCP 요청의 Authorization header를 확인하세요.

Authorization: Bearer <MCP_AUTH_TOKEN>

Hermes의 TOSSINVEST_MCP_AUTH_TOKEN에는 Bearer 없이 토큰 값만 저장해야 합니다.

/readyz가 503을 반환함

• TOSSINVEST_CLIENT_ID 확인

• TOSSINVEST_CLIENT_SECRET 확인

• 컨테이너의 외부 네트워크 연결 확인

• 토스증권 Open API 점검 여부 확인

docker compose logs tossinvest-mcp

account-not-configured

.env에 올바른 TOSSINVEST_ACCOUNT_SEQ가 필요합니다. 값을 수정한 뒤 컨테이너를 다시 생성하세요.

docker compose up -d --force-recreate

거래 도구가 보이지 않음

다음을 모두 확인하세요.

1. TOSSINVEST_ENABLE_TRADING=true

2. 원화·달러 주문 한도가 모두 설정됨

3. 컨테이너가 설정 변경 후 다시 생성됨

4. Hermes tools.include에 거래 도구가 추가됨

origin-not-allowed

브라우저 기반 MCP 클라이언트가 Origin header를 보내는 경우 해당 주소를 설정합니다.

MCP_ALLOWED_ORIGINS=https://agent.example.com,https://another.example.com

Origin을 보내지 않는 일반 서버 클라이언트와 Hermes 로컬 연결은 이 목록이 비어 있어도 사용할 수 있습니다.

order-state-unknown

주문 요청이 전송된 뒤 응답을 받지 못한 상태입니다. 절대 같은 실행 도구를 반복 호출하지 마세요.

1. list_orders(status="OPEN") 조회

2. 종료 주문도 필요하면 list_orders(status="CLOSED") 조회

3. 발견된 주문 ID를 get_order로 확인

4. 주문 존재 여부가 확정되기 전까지 새 주문 금지

rate-limit-exceeded

조회 요청은 서버가 Retry-After를 따라 제한적으로 재시도합니다. 계속 발생하면 호출 빈도를 줄이세요. 주문 요청은 rate limit 오류가 발생해도 자동 재시도하지 않습니다.

현재 제한사항

• 토스증권 Open API가 제공하는 REST API만 사용합니다.

• WebSocket 기반 실시간 스트리밍을 제공하지 않습니다.

• 시세 갱신이 필요한 에이전트는 조회 API를 polling해야 합니다.

• OAuth token과 주문 preview는 메모리에만 저장됩니다.

• 서버 재시작 시 기존 preview와 확인 문구는 무효화됩니다.

• 안전한 일회용 preview를 위해 단일 worker로 실행합니다.

• 현재 구성은 단일 인스턴스를 전제로 하며 수평 확장용 공유 상태 저장소가 없습니다.

• 공식 모의투자 또는 sandbox가 문서화되지 않은 경우 실계좌 주문 테스트가 될 수 있습니다.

• CI는 실제 토스증권 계정에 연결하거나 실주문을 실행하지 않습니다.

기여

버그 수정, 문서 개선, 테스트 추가를 환영합니다. 시작하기 전에 CONTRIBUTING.md와 CODE_OF_CONDUCT.md를 확인하세요.

보안 취약점은 공개 Issue 대신 SECURITY.md의 비공개 신고 절차를 이용하세요.

라이선스

MIT License

Copyright (c) 2026 cha2hyun