JeongSeongMok/tossinvest-openapi-mcp

> **토스증권 Open API**를 개발자와 AI 에이전트가 쉽게 탐색·연동할 수 있도록 돕는 MCP(Model Context Protocol) 서버.
**언어:** **한국어** · English · 日本語
이 서버는 토스증권 OpenAPI(Toss Securities Open API, 토스증권 오픈API) 명세를 내장하여 MCP 도구로 제공합니다. **읽기 전용 문서/탐색 서버**로, 실제 API를 호출하거나 주문을 실행하지 않으며 어떤 인증 정보도 필요로 하지 않습니다. Claude·Cursor·Codex 등 MCP를 지원하는 AI 코딩 에이전트에 연결한 뒤 *"토스증권 API로 주문을 어떻게 넣어?"* 같이 물어보면, 명세에 근거한 정확한 답변과 코드 샘플을 얻을 수 있습니다.
> 토스증권 Open API 연동을 처음 시작하는 개발자가 엔드포인트·인증·주문/시세 API 구조를 빠르게 파악하고, AI 에이전트로 코드를 생성하는 데 활용할 수 있습니다.
---
개요
MCP 클라이언트에 연결하면 에이전트는 다음을 할 수 있습니다.
- 토스증권 Open API의 모든 엔드포인트·카테고리 탐색
- 요청/응답 스키마와 예시 조회
- 키워드로 엔드포인트·데이터 모델 검색
- 유스케이스 중심 연동 가이드 활용 — 인증, 시세·종목, 시장 지표, 랭킹, 수급 동향, 계좌·자산, 주문, 조건주문
- **curl / TypeScript / Python** 요청 코드 샘플 생성
수록 범위
번들된 명세는 **v1.2.17** 기준이며, 13개 카테고리 · 36개 엔드포인트 · 90개 데이터 모델을 포함합니다.
| 그룹 | 카테고리 |
|---|---|
| 인증 | Auth |
| 시세·종목 정보 | Market Data, Stock Info(기본 정보 + 국내 수급 동향), Market Info, Ranking, Market Indicators(지수·국채) |
| 계좌·자산 | Account, Asset |
| 주문 | Order, Order History, Order Info |
| 조건주문 | Conditional Order, Conditional Order History (SINGLE·OCO·OTO) |
> ⚠️ **주의**: 이 도구는 토스증권 공개 OpenAPI 문서를 *설명*하는 **비공식** 도구입니다. 실제 매매 실행, 계좌 접근, 인증 정보 전송을 하지 않습니다. 운영 적용 전 반드시 토스증권 Open API 공식 문서로 검증하세요.
제공 도구
| 도구 | 용도 |
|---|---|
| get_api_overview | API 전체 개요 (여기서 시작) |
| list_categories | 카테고리(태그) 목록과 설명 |
| list_endpoints | 엔드포인트 목록 (카테고리 필터 가능) |
| search_endpoints | 키워드 기반 엔드포인트 검색 |
| get_endpoint | 단일 엔드포인트 상세(파라미터·본문·응답) |
| list_schemas | 데이터 모델 이름 목록/필터 |
| get_schema | 단일 데이터 모델의 필드 트리 |
| get_integration_guide | 호출 시퀀스를 포함한 유스케이스 가이드 |
| generate_code_sample | 엔드포인트별 curl/TS/Python 코드 샘플 |
요구 사항
- Node.js **18 이상**
- MCP 호환 클라이언트 (Claude Desktop, Claude Code, Cursor 등)
설치 및 사용 (stdio)
이 서버는 **stdio** 방식으로 MCP를 통신합니다. **실행 명령**을 하나 고른 뒤, 해당 블록을 MCP 클라이언트 설정에 붙여 넣으면 됩니다.
**실행 명령**
| 소스 | 명령 / 인자 |
|---|---|
| **npm (권장)** | npx · -y, tossinvest-openapi-mcp |
| GitHub (npm 없이 최신 소스를 직접 실행) | npx · -y, github:JeongSeongMok/tossinvest-openapi-mcp |
| 소스에서 실행 (git clone + npm install + npm run build 후) | node · /절대/경로/tossinvest-openapi-mcp/dist/index.js |
> Node.js 18+ 만 있으면 npx -y tossinvest-openapi-mcp 로 바로 실행됩니다. GitHub 명령은 npm 을 거치지 않고 저장소를 직접 클론·빌드·실행하므로, 항상 최신 소스가 필요할 때 사용합니다.
Claude (Claude Desktop / Claude Code / Cursor) — JSON
Codex CLI — TOML (~/.codex/config.toml)