tossinvest-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| TOSSINVEST_MCP_HOST | No | HTTP bind address. Docker default is 0.0.0.0. CLI option --host overrides this. | 127.0.0.1 |
| TOSSINVEST_MCP_PORT | No | HTTP port. The MCP path is /mcp. CLI option --port overrides this. | 8000 |
| TOSSINVEST_CLIENT_ID | Yes | Tossinvest Open API client_id issued from Tossinvest WTS. | |
| TOSSINVEST_ACCOUNT_SEQ | No | Default accountSeq for account tools. Optional; can be overridden by the account_seq tool argument. | |
| TOSSINVEST_TOKEN_CACHE | No | Token cache file path. Docker uses /cache/token.json. | ~/.cache/tossinvest-mcp/token.json |
| TOSSINVEST_CLIENT_SECRET | Yes | Tossinvest Open API client_secret issued from Tossinvest WTS. | |
| TOSSINVEST_ENABLE_ORDERS | No | Set to 1 or true to register the 6 order and conditional-order tools. Default is off. | false |
| TOSSINVEST_MCP_TRANSPORT | No | MCP transport: stdio or streamable-http. Docker default is streamable-http. CLI option --transport overrides this. | stdio |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
토스증권 Open API 로 국내·미국 주식 시세, 종목 정보, 섹터, 본인 계좌를 조회한다 (읽기 전용).
심볼: 국내는 6자리 종목코드(005930), 미국은 티커(AAPL). 종목명만 알면 list_market_stocks(market, query=이름) 로 코드를 찾는다.
수급 tool(투자자·프로그램·공매도·신용·대차)은 국내 종목만 지원한다.
계좌 tool 은 accountSeq 가 필요하다. 설정값이 없으면 list_accounts 로 확인해 넘긴다.
가격·수량·금액은 문자열 숫자이고, 등락률·수익률·수수료율은 소수 비율이다 (0.1 = 10%).
응답 데이터는 본인 매매 목적으로만 쓴다. 제3자에게 배포하지 않는다.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| get_pricesA | 국내·미국 종목의 현재가(최종 체결가)를 한 번에 최대 200개 조회한다. 등락률·기준가는 없다. 전일 대비 등락이 필요하면 get_stock_rankings 를 쓴다. |
| get_orderbookB | 종목의 매수·매도 호가와 잔량을 조회한다. 국내는 KRX+NXT 통합 호가. |
| get_recent_tradesA | 종목의 당일 최근 체결 내역을 최신순으로 최대 50건 조회한다. 이보다 과거로 넘기는 페이지는 없다. |
| get_price_limitsA | 종목의 당일 상한가·하한가를 조회한다. |
| get_candlesA | 종목의 캔들(OHLCV)을 최신순으로 조회한다 (분봉·일봉, 최대 200개). 과거로 넘기려면 응답의 nextBefore 를 before 에 넣는다. 1분봉은 국내 2022-11-23, 미국 2021-12-01 이전 데이터가 없다. |
| get_stock_infoA | 종목 기본 정보를 최대 200개 조회한다. 이름, 시장, 통화, 상장 상태, 거래정지 여부 등을 담는다. |
| list_market_stocksA | 거래소별 전체 종목 목록(심볼, 한글 이름, 유형, ISIN)을 조회한다. 종목명으로 종목코드를 찾을 때 query 와 함께 쓴다. 마켓당 수천 건이므로 query 없이 부르면 응답이 크다. 하루 1회 갱신 데이터라 당일(KST) 동안 캐싱한다. |
| get_stock_warningsA | 종목의 매수 유의사항을 조회한다. 정리매매, 단기과열, 투자경고·위험, VI 발동, 신주인수권. |
| get_investor_tradingA | [국내 전용] 종목의 투자자별 일별 매수·매도·순매수 거래량. 투자자는 개인·외국인·기관·기타법인. 기관 세부 분류, 외국인 보유 현황, CFD 잔고 포함. KRX+NXT 통합 기준. |
| get_program_tradingB | [국내 전용] 종목의 일별 프로그램매매(차익·비차익) 매수·매도·순매수 거래량. KRX 만 집계한다 (NXT 제외). |
| get_short_sellingA | [국내 전용] 종목의 일별 공매도 거래량·거래대금·비중. 당일분은 저녁에 확정된다. |
| get_credit_tradingA | [국내 전용] 종목의 일별 신용거래(신용융자·신용대주) 신규·상환·잔고. 잔고 비율·공여율 포함. T+1 에 반영된다. |
| get_securities_lendingB | [국내 전용] 종목의 일별 대차거래(기관 간 주식 대여) 체결·상환·잔고. |
| get_exchange_rateB | KRW↔USD 환율(1분 갱신, 참고용)을 조회한다. 실제 주문 환율과 다를 수 있다. |
| get_market_calendarA | 장 운영 시간을 전일·당일·익일 3영업일분 조회한다. 시간은 모두 KST. KR: KRX+NXT 통합 기준 장전·정규·장후 세션. integrated 가 null 이면 휴장. US: 데이마켓·프리·정규·애프터 세션. 휴장이면 4개 세션 모두 null. |
| get_stock_rankingsB | 주식 랭킹(최대 100위)을 조회한다. 순위와 현재가·기준가·등락률·거래량·거래대금을 담는다. 종목별 전일 기준가·등락률은 이 응답에만 있다. 과거 날짜 랭킹은 없다. |
| get_investor_trading_rankingsA | [국내 전용] 외국인·기관·개인별 순매수·순매도 상위 종목을 조회한다. 최근 영업일 기준, 거래액순. |
| get_market_indicator_pricesA | 국내 지수(KOSPI·KOSDAQ)와 한국 국채 금리(2·3·5·10·20·30년) 현재가를 조회한다. 국채 값은 수익률(%)이다. 해외 지수는 제공되지 않는다. |
| get_market_indicator_candlesB | 국내 지수·국채의 캔들(OHLC)을 최신순으로 조회한다 (최대 200개). |
| get_market_investor_tradingB | 코스피·코스닥 시장 전체의 투자자별 매수·매도 거래대금을 조회한다. 투자자는 개인·외국인·기관·기타법인 (기관 세부 분류 포함). |
| list_sectorsA | 토스증권 섹터 분류 전체(대·중·소분류 계층)를 조회한다. depth 0=대분류, 1=중분류, 2=소분류. 다른 섹터 tool 의 sector_id 는 여기서 찾는다. 하루 1회 갱신 데이터라 당일(KST) 동안 캐싱한다. |
| get_sectorB | 섹터 기본 정보와 지정 시장 기준 기간별(1d~1y) 등락률을 조회한다. |
| get_sector_stocksA | 섹터(하위 섹터 포함)에 속한 보통주를 시가총액 내림차순으로 조회한다. 금액은 미국 종목도 원화 환산값이다. |
| get_sector_etfsA | 섹터 관련 ETF 의 심볼·이름을 조회한다 (하위 섹터 미포함). 시세는 get_prices 로 조회한다. |
| get_sector_rankingsB | 섹터 랭킹(대·중분류, 최대 100위)을 조회한다. |
| list_accountsA | 계좌 목록을 조회한다. 다른 계좌 tool 의 account_seq 값을 여기서 확인한다. 종합매매(BROKERAGE) 계좌만 나온다. 계좌 번호는 끝 4자리만 보여준다. |
| get_holdingsB | 보유 주식(국내·미국)과 평가금액·손익 합계를 조회한다. 손익률은 소수 비율이다 (0.1 = 10%). |
| list_ordersA | 주문 목록을 조회한다. 앱·WTS 주문도 포함, 주문 1건 = 1행(분할 체결 합산). OPEN 은 페이지 없이 전량, CLOSED 는 limit 개씩 cursor 로 넘긴다. |
| get_orderA | 주문 1건의 상세(상태·체결 내역)를 조회한다. 종료된 주문도 조회된다. |
| get_buying_powerA | 현금 기준 매수 가능 금액(미수 미발생)을 조회한다. 미국 주문은 자동환전이 없으므로 USD 잔액을 따로 본다. |
| get_sellable_quantityC | 종목의 매도 가능 수량을 조회한다. |
| get_commissionsA | 계좌의 국내·미국 매매 수수료율을 조회한다. 소수 비율 (0.00015 = 0.015%). |
| list_conditional_ordersB | 조건주문(SINGLE·OCO·OTO) 목록을 조회한다. 앱에서 등록한 조건주문도 포함. |
| get_conditional_orderA | 조건주문 1건의 상세(감시 조건·트리거·발생 주문)를 조회한다. 종료된 조건주문도 조회된다. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 34 tools
Most tools are cleanly separated by resource scope (single stock vs market-wide vs sector) and by data type (prices, candles, orderbook, trades, short selling, credit, lending). The riskiest cluster is the three 'rankings' tools (get_stock_rankings, get_investor_trading_rankings, get_sector_rankings) plus get_investor_trading vs get_market_investor_trading, but the descriptions explicitly state scope and clarify what only one tool returns (e.g., rankings are the only source of prior-close change rates). No two tools appear to do the same thing.
Names are uniformly snake_case with a predictable get_/list_ verb split (get_ for single/aggregate reads, list_ for collections), and market-data tools are systematically prefixed by domain (market_indicator_, sector_, investor_trading_*). A few minor deviations exist, such as get_prices (plural) alongside singular get_stock_info and list_market_stocks, but the pattern remains readable and predictable.
At 34 tools the surface is well beyond the 3-15 sweet spot and past even the heavy 16-25 band. Each tool covers a genuinely narrow endpoint (per-metric daily series for program trading, short selling, credit, lending), which forces the agent to scan a long list to pick the right one, even though nothing is strictly redundant.
The market-data side is thorough (quotes, candles, orderbook, fills, limits, rankings, indicators, sectors, investor/short/credit/lending flows) and the account side covers read workflows (accounts, holdings, orders, conditional orders, buying power, sellable qty, commissions). However, there are no write operations — no place/cancel/modify order and no conditional-order creation — which is a notable gap for a brokerage server, though it may be an intentional read-only design.