Skip to main content
Glama
Sign In
toss-securities-mcp

toss-securities-mcp

by hamcheeseburger
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

toss-securities-mcp

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

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

⚠️ 디스클레이머

  • 이 프로젝트는 토스증권 공식 제품이 아닌 비공식 커뮤니티 도구입니다.

  • 사용 시 토스증권 Open API 약관 준수 책임은 사용자 본인에게 있습니다.

  • 시세 정보는 본인 매매 목적으로만 사용 가능합니다 (약관).

  • 이 서버는 읽기 전용 조회 도구만 제공합니다. 주문(매수/매도) 기능은 없습니다.

  • self-hosted 전용입니다. 타인에게 호스팅 서비스 형태로 제공하지 마세요.

Related MCP server: tossinvest-mcp

제공 도구

도구

설명

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

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

설정

  1. API 키 발급 — 토스증권 WTS 로그인 → 설정 → Open API 에서 client_id / client_secret 발급

  2. 환경변수 작성

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

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

uv run scripts/smoke_test.py

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

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

Claude Desktop 연결

claude_desktop_config.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 연결

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

개발

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

로드맵

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

  • Phase 1 (이 저장소): 토스 MCP — 계좌·시세 조회

  • Phase 2: portfolio-aggregator-mcp — 멀티 증권사 통합, FIFO 누적 실현손익(Lifetime Realized P/L), 행동 패턴 분석

  • Phase 4: NH QV MCP

라이선스

MIT

Available Tools

4 tools
get_account_balanceA

계좌 잔고 요약을 조회합니다.

사용자가 "내 계좌 잔고", "총 자산", "예수금/현금 얼마 있어" 등을 물을 때 호출하세요. 보유 주식 평가 요약(매입금액·평가금액·평가손익)과 현금(매수 가능 금액, KRW/USD)을 함께 반환합니다.

참고: 현금은 미수를 제외한 '현금 기반 매수 가능 금액'으로, 예수금과 미세하게 다를 수 있습니다. 금액 필드는 정밀도 보존을 위해 문자열입니다.

Inputs: no named parameters. Returns: object

get_holdingsA

보유 주식을 조회합니다.

사용자가 "보유 종목", "내 주식", "뭐 들고 있어", "삼성전자 몇 주 있어" 등을 물을 때 호출하세요. 종목별 수량·평단가·현재가·평가손익과 전체 합산 요약을 반환합니다. symbol을 지정하면 해당 종목만 조회합니다 (국내: 6자리 코드 예 "005930", 미국: 티커 예 "AAPL").

금액·수량 필드는 정밀도 보존을 위해 문자열입니다. rate 필드는 소수 (0.1077 = +10.77%)입니다.

Inputs: symbol. Returns: object

get_stock_priceA

종목의 현재가를 조회합니다.

사용자가 "삼성전자 지금 얼마야", "AAPL 현재가" 등 시세를 물을 때 호출하세요. symbols는 콤마로 구분해 최대 200개까지 한 번에 조회할 수 있습니다 (국내: 6자리 코드 예 "005930", 미국: 티커 예 "AAPL,MSFT").

⚠️ 시세 정보는 토스증권 약관상 본인 매매 목적으로만 사용할 수 있습니다.

Inputs: symbols (required). Returns: object

get_transactionsA

기간 내 거래(체결) 내역을 조회합니다.

사용자가 "거래내역", "매매 내역", "지난달 뭐 샀어/팔았어", "체결 내역" 등을 물을 때 호출하세요. 날짜는 "YYYY-MM-DD" 형식이며 주문 생성 시간(KST) 기준 inclusive입니다. symbol 지정 시 해당 종목만 조회합니다.

only_filled=True(기본)면 체결된 주문(FILLED, PARTIAL_FILLED)만 반환하고, False면 취소·거부된 주문도 포함합니다. 각 항목의 execution 필드에 체결 수량·평균 체결가·수수료·세금이 담겨 있습니다.

Inputs: end_date (required), start_date (required), symbol, only_filled. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.4/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool targets a distinct aspect of securities (balance, holdings, price, transactions). No overlap in purpose; descriptions clearly differentiate them.

    Naming Consistency5/5

    All tools follow a consistent 'get_noun' pattern in snake_case, making it easy to infer functionality from names.

    Tool Count5/5

    Four tools cover the core read-only needs for a securities account (balance, holdings, price, transactions). This is well-scoped and not excessive.

    Completeness4/5

    Covers essential read operations but lacks any write/trading tools. For a purely informational server it is complete; for trading, order placement is missing.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • kiwoom-mcp

      kwonsw812
      A
      license
      A
      quality
      D
      maintenance
      An MCP server that enables natural language control of Kiwoom Securities accounts through Claude Desktop. It provides tools for stock price lookup, buying and selling stocks, and analyzing portfolios or trade history via the Kiwoom REST API.
      11
      2
      MIT

    • tossinvest-mcp

      ryum91
      A
      license
      A
      quality
      D
      maintenance
      MCP server wrapping Toss Securities Open API, enabling stock price queries and trading for Korean and US stocks via natural language.
      36
      49 npm
      MIT

    • K-invest

      ianlyoo
      A
      license
      Not graded
      quality
      B
      maintenance
      Read-only MCP server that connects LLMs to personal investment accounts (Toss Securities, KIS), market data, SEC filings, and Binance futures for context-aware investment responses.
      1
      MIT

    • tossinvest-api-mcp

      Kuco-dev
      A
      license
      A
      quality
      D
      maintenance
      A local MCP server that automatically generates tools from Toss Securities' official OpenAPI spec, enabling real API calls with multi-layered order safety and OAuth 2.0 authentication.
      36
      1
      MIT