sc-mcp

Scalable Capital 증권 계좌를 MCP 호환 어시스턴트에 연결하세요. 이 서버는 Scalable Capital 공식 sc CLI를 감싸는 가벼운 읽기 전용 래퍼입니다. 에이전트가 Claude Code, Claude Desktop, Codex, Cursor 및 VS Code에서 동일한 설정으로 포트폴리오, 거래 내역, 분석, 시세, 차트, 관심 목록 및 알림을 가져옵니다.

기능

• 실시간 증권 데이터 — 개요, 보유 종목, 거래 내역, 분석, 현금 내역, 성과 차트, 시세, 증권 뉴스.

• 포트폴리오 관리 추가 기능 — 관심 목록, 가격 알림, 포트폴리오 그룹 및 적립식 투자 설정.

• 기본적으로 빠름 — 읽기 응답은 SQLite 파일에 캐시됩니다(재시작 후에도 유지, 설정 참조).

• 안전 우선 — 거래나 주문이 없습니다. 쓰기 도구는 선택하지 않으면 비활성화되어 있습니다. 자금 이동 명령은 설계상 존재하지 않습니다.

• 어디서나 실행 — 데스크톱 클라이언트용 일반 stdio, 원격 액세스용 HTTP, 또는 완전히 독립적인 Docker 이미지.

[!Warning] 비공식. Scalable Capital의 sc CLI를 감싸는 커뮤니티 래퍼입니다. Scalable Capital과 제휴하거나 보증하지 않습니다. 자체 MCP 서버가 나올 때까지의 임시 방편이며, 출시되면 사용이 중단될 가능성이 높습니다.

보증 없음. MIT 라이선스에 따라 "있는 그대로" 제공됩니다. 손실, 손해, 부정확한 데이터 또는 재정적 결과에 대해 책임을 지지 않습니다. 재정적 조언이 아닙니다. 실행에 옮기기 전에 확인하세요.

도구

읽기 전용 도구는 증권사에 실시간으로 접속합니다. 성공적인 응답은 재시작 후에도 유지되는 SQLite 파일에 5분(설정 가능) 동안 캐시됩니다.

⚠️ = SC_MCP_ENABLE_WRITES=true 필요, 기본적으로 비활성화.

sc CLI는 trade 및 savings-plans add/remove도 제공합니다. 이들은 의도적으로 노출되지 않습니다 — 자금 이동 명령은 완전히 범위 밖입니다(위의 쓰기 도구는 관심 목록, 알림 및 그룹만 다룹니다).

빠른 시작

세 가지 경로 중 하나를 선택하세요. 모두 작동하는 서버로 이어집니다:

Claude Code 플러그인

/plugin marketplace add NinjaEde/mcp-scalable-capital
/plugin install sc-mcp

그러면 scalable-capital MCP 서버와 Claude에게 도구를 사용할 시기와 방법을 알려주는 스킬이 등록됩니다.

uvx 한 줄 명령

uvx --from git+https://github.com/NinjaEde/mcp-scalable-capital@v0.2.0 sc-mcp

모든 MCP 클라이언트를 해당 명령어로 지정하세요(sc-mcp가 stdio로 시작됨, 버전 관리에 따라 태그 고정).

요구 사항

1. PATH에 uv — Docker를 사용하는 경우 건너뜁니다.

2. PATH에 sc CLI ( 인증 참조).

3. 인증된 세션: sc login (인증 참조).

Docker는 CLI와 이 서버를 모두 번들로 제공하므로, 유일한 수동 단계는 아래 로그인입니다.

인증

모든 sc_* 도구는 Scalable Capital의 공식 sc CLI를 호출하며, 이 CLI는 머신당(또는 Docker 볼륨당) 한 번 설치 및 로그인되어야 합니다.

CLI 설치

macOS (Homebrew):

brew install scalablecapital/tap/scalable-cli

Linux (Docker 이미지에 포함된 바이너리와 동일): 아키텍처에 맞는 공식 빌드를 다운로드하고 sc를 PATH에 추가하세요:

ARCH=$(uname -m)   # x86_64 or aarch64
curl -fSL "https://github.com/ScalableCapital/scalable-cli/releases/download/v0.6.0/sc-v0.6.0-linux-${ARCH}-gnu.tar.gz" -o /tmp/sc.tar.gz
tar xzf /tmp/sc.tar.gz -C /tmp
sudo install -m 0755 /tmp/sc-v0.6.0-linux-${ARCH}-gnu/sc /usr/local/bin/sc

확인:

sc --version   # e.g. "sc 0.6.0"

로그인 (한 번)

sc login       # device flow: open the printed URL, confirm, done
sc whoami      # confirm the session works

나중에 도구가 *"세션이 만료되었을 수 있습니다 — sc login을 실행하세요"*라고 보고하면 sc login을 다시 실행하세요.

세션 저장 위치

~/.config/scalable-cli/:

헤드리스 / 키링 없는 환경 (Docker, CI, 서버): CLI는 기본적으로 OS 키링을 사용합니다. 키링이 없는 경우 일반 파일을 가리키도록 설정하세요(Docker 이미지는 docker/entrypoint.sh에서 이를 자동으로 수행합니다):

# ~/.config/scalable-cli/config.toml
[auth]
session_backend = "file"

그런 다음 sc login을 다시 실행하세요. 세션은 session.json에 저장되고 재시작 후에도 유지됩니다.

팁: 두 번 로그인하는 대신 컨테이너 내에서 호스트 세션을 재사용하세요:

docker cp ~/.config/scalable-cli/session.json sc-mcp:/home/sc/.config/scalable-cli/session.json
docker compose restart

해당 파일을 비밀번호처럼 취급하고 절대 커밋하지 마세요.

클라이언트와 통합

Claude Code (수동)

claude mcp add scalable-capital -- uvx --from git+https://github.com/NinjaEde/mcp-scalable-capital@v0.2.0 sc-mcp

Cursor

Cursor에 추가 — 또는 .cursor/mcp.json (또는 ~/.cursor/mcp.json)에 추가:

{
  "mcpServers": {
    "scalable-capital": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/NinjaEde/mcp-scalable-capital@v0.2.0", "sc-mcp"]
    }
  }
}

Codex

~/.codex/config.toml에 추가:

[mcp_servers.scalable-capital]
command = "uvx"
args = ["--from", "git+https://github.com/NinjaEde/mcp-scalable-capital@v0.2.0", "sc-mcp"]

Claude Desktop (번들, 설정 편집 불필요)

sc-mcp.mcpb를 다운로드한 후, Claude Desktop에서 설정 → 확장 프로그램 → 확장 프로그램 설치로 이동하여 파일을 선택하세요.

[!Note] Claude Desktop이 uvx를 찾을 수 없는 경우, 확장 프로그램 설정을 열고 전체 경로(예: /opt/homebrew/bin/uvx)를 설정하세요. macOS의 GUI 앱은 항상 셸 PATH를 상속하지 않습니다.

VS Code / 기타 MCP 클라이언트

{
  "mcpServers": {
    "scalable-capital": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/NinjaEde/mcp-scalable-capital@v0.2.0", "sc-mcp"]
    }
  }
}

@v0.2.0 태그를 고정하세요(버전 관리 참조). 최신 main을 추적하려면 태그를 제거하세요.

Docker

전체 스택(이 서버 및 sc CLI)이 컨테이너에서 실행되므로 Docker만 있으면 됩니다(로컬 uv, Python 또는 sc 불필요):

docker compose up -d --build              # build + start on http://localhost:8000/mcp
docker compose run --rm sc-login          # first time only — interactive device flow

세션은 sc-cli-config 볼륨에 저장되고 재시작 후에도 유지됩니다. docker-compose.yml에서 SC_MCP_ENABLE_WRITES: "true"를 설정하지 않으면 쓰기는 비활성화 상태로 유지됩니다.

HTTP 지원 MCP 클라이언트를 서버 URL로 지정하세요:

{
  "mcpServers": {
    "scalable-capital": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

컨테이너는 scalable.capital에 직접 연결됩니다. sc login의 장치 흐름 URL은 호스트에서와 동일하게 작동합니다. 브라우저에서 따라가기만 하면 됩니다. 이미지에는 이미 session_backend = "file" 설정이 포함되어 있습니다(인증 참조).

호환성

sc 0.6.x에서 테스트되었습니다. CLI는 1.0 이전 버전이며 명령어 표면이 마이너 버전 간에 변경될 수 있습니다. 서버는 시작 시 설치된 sc가 테스트된 주.부 버전과 다른 경우 stderr에 경고를 기록합니다. sc는 Python 종속성이 아닌 외부 바이너리이므로 이것이 유일하게 적용 가능한 제한입니다. 경고가 표시되고 도구가 오작동하는 경우 버전 불일치가 원인일 가능성이 높습니다.

설정

개발

uv sync
uv run sc-mcp          # starts the stdio server
# or
SC_MCP_TRANSPORT=streamable-http uv run sc-mcp
uv run pytest

sc와 동기화를 유지하는 방법(도구 추가/업데이트 시기, SUPPORTED_SC_VERSION 범프, 읽기 전용 불변성)은 CLAUDE.md에 문서화되어 있습니다.

버전 관리

SemVer — 도구가 공개 API입니다:

릴리스는 vX.Y.Z로 태그가 지정됩니다. uvx --from git+...를 통해 설치할 때 태그를 고정하세요. 그렇지 않으면 기본 브랜치를 추적하여 도구 표면이 변경될 수 있습니다. 대부분의 범프는 sc CLI 변경으로 인해 발생합니다(호환성 참조). 버전은 이 패키지 자체의 버전이지 sc 버전이 아닙니다.

라이선스

MIT