toss-mcp

토스증권 Open API 를 MCP 도구로 노출하는 읽기 전용 Claude Code 플러그인입니다. LLM 이 국내·미국 주식의 시세, 종목 정보, 환율·장 운영 시간, 랭킹을 조회할 수 있습니다.

계좌 조회와 주문(생성·정정·취소)은 구현하지 않았습니다. 이 서버는 어떤 부수효과도 일으키지 않습니다.

1. 토스증권 Open API 신청

플러그인을 설치하기 전에 API 자격증명부터 발급받아야 합니다.

3번을 건너뛰면 모든 호출이 403 으로 차단됩니다. 등록된 허용 IP 목록에 없는 IP 에서의 요청은 토스 측에서 거부합니다. 집·회사 등 실행할 환경의 공인 IP 를 등록하세요. ISP 가 IP 를 바꾸면 다시 등록해야 합니다.

별도의 심사나 승인 대기는 없습니다. 발급 즉시 사용할 수 있습니다. client_secret 은 발급 화면을 벗어나면 다시 볼 수 없으니 그 자리에서 보관하세요.

Related MCP server: tossinvest-mcp

2. 설치

Claude Code 와 Codex 양쪽에서 같은 저장소를 플러그인으로 설치할 수 있습니다. 자격증명을 받는 방식만 다릅니다.

Claude Code

/plugin marketplace add jaywapp/toss-readonly-mcp
/plugin install toss-mcp@toss-readonly-mcp

플러그인을 활성화하면 client_id / client_secret 을 묻는 입력창이 뜹니다. 두 값 모두 민감 정보로 처리되어 settings.json 이 아닌 보안 저장소 (macOS Keychain, 그 외 플랫폼은 ~/.claude/.credentials.json)에 저장됩니다.

가상환경은 ${CLAUDE_PLUGIN_DATA}/venv 에 만들어져 플러그인을 업데이트해도 재사용됩니다.

설정을 바꾸려면 /plugin → toss-mcp → Configure 를 사용합니다.

Codex

Codex 에는 플러그인 설정값을 묻는 절차가 없습니다. 자격증명을 먼저 환경변수로 등록한 뒤 설치합니다.

[Environment]::SetEnvironmentVariable('TOSS_CLIENT_ID', '<client_id>', 'User')
[Environment]::SetEnvironmentVariable('TOSS_CLIENT_SECRET', '<client_secret>', 'User')
# 새 터미널을 열어 반영

codex plugin marketplace add jaywapp/toss-readonly-mcp
codex plugin add toss-mcp@toss-readonly-mcp

.codex.mcp.json 의 env_vars 가 위 두 변수를 서버 프로세스로 전달합니다. 등록됐는지는 codex mcp list 의 toss 행에서 확인할 수 있습니다.

Codex 는 플러그인을 ~/.codex/plugins/cache/ 로 복사해 실행하며, 여기에 가상환경이 생깁니다. Claude Code 와 달리 업데이트하면 다시 만들어집니다.

첫 실행

두 플랫폼 모두 첫 호출 때 uv 가 의존성을 설치하느라 십여 초 걸립니다.

새 세션에서 "삼성전자 주가 알려줘" 라고 물어보세요. search_symbol → get_price 순으로 호출되면 정상입니다.

TOSS_CLIENT_ID가 설정되지 않았습니다 가 뜨면 자격증명이 비어 있는 것이고, 403 이 뜨면 허용 IP 등록(1번 3단계)이 안 된 것입니다.

3. 도구

종목 검색

토스 API 에는 종목명 검색 엔드포인트가 없어서, 상장 종목 목록을 로컬 SQLite 에 캐시해 직접 제공합니다. 첫 검색 시 수집하며 이후 TOSS_SYMBOL_TTL_DAYS 마다 자동 갱신됩니다.

시세

get_price 응답에는 로컬 종목 마스터에서 찾은 종목명이 API 추가 호출 없이 붙습니다.

include_change 는 기본값이 False 입니다. 토스의 현재가 응답에 등락률이 없어서, 켜면 종목마다 일봉을 추가로 조회합니다 (차트 API 는 초당 5회 제한이라 종목이 많으면 느려집니다).

종목 정보

시장 정보

랭킹·지표

4. 설정값

플러그인 설정으로 노출되는 것은 자격증명 두 개뿐입니다. 나머지는 환경변수로 조정합니다 (기본값 그대로 두어도 동작합니다).

호출량은 토스가 공개한 그룹별 초당 한도(시세 10회, 차트 5회, 종목 5회, 시장정보 3회)에 맞춰 클라이언트에서 미리 조절합니다. 429 를 받아 재시도하는 것보다 싸기 때문입니다.

5. 플러그인 없이 쓰기

MCP 서버 단독으로도 등록할 수 있습니다. 소스를 직접 고칠 때 이 방식이 편합니다.

git clone https://github.com/jaywapp/toss-readonly-mcp.git toss-mcp
cd toss-mcp
uv sync
copy .env.example .env    # client_id / client_secret 채우기

claude mcp add --scope user toss -- uv --directory <절대경로>\toss-mcp run toss-mcp

이때는 자격증명을 .env 에서 읽습니다. 환경변수가 있으면 그쪽이 우선합니다. .env 는 .gitignore 에 있으니 커밋되지 않습니다.

개발

uv run pytest              # 네트워크를 타지 않는 전체 스위트
uv run pytest -m smoke     # 실제 API 호출 (자격증명 + 허용 IP 등록 필요)

문서

• 설계: docs/superpowers/specs/2026-08-04-toss-mcp-design.md

• 구현 계획: docs/superpowers/plans/2026-08-04-toss-mcp.md

• 토스 Open API 개요: https://openapi.tossinvest.com/openapi-docs/overview.md

• 토스 OpenAPI 스펙: https://openapi.tossinvest.com/openapi-docs/latest/openapi.json (v1.2.9 기준)

라이선스

MIT