Alpaca MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

동일한 툴로 페이퍼 또는 실계좌 모두에 대해 작동합니다
주식, ETF, 암호화폐, 옵션을 지원합니다
Alpaca Market Data에서 과거 봉 데이터 + 실시간 호가
완전한 주문 생명주기: 발주, 수정, 취소, 상태 확인
포지션, 계좌 자산, 손익을 1급 툴로 이용할 수 있습니다

라이브 데모

실제 사용 모습

alpaca.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "alpaca": {
      "command": "uvx",
      "args": [
        "alpaca-mcp-server"
      ]
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "alpaca": {
      "command": "uvx",
      "args": [
        "alpaca-mcp-server"
      ]
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "alpaca": {
      "command": "uvx",
      "args": [
        "alpaca-mcp-server"
      ]
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "alpaca": {
      "command": "uvx",
      "args": [
        "alpaca-mcp-server"
      ]
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "alpaca",
      "command": "uvx",
      "args": [
        "alpaca-mcp-server"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "alpaca": {
      "command": {
        "path": "uvx",
        "args": [
          "alpaca-mcp-server"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add alpaca -- uvx alpaca-mcp-server

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: Alpaca

감시 목록의 일일 장 전 브리프 생성

👤 활발한 개인 매매자 ⏱ ~10 min beginner

언제 쓸까: 개장 전 감시 중인 20개 종목을 30초 안에 확인하고 싶을 때 — 장외 변동, 실적, 관련 뉴스를 확인합니다.

사전 조건

Alpaca 계좌 (무료 페이퍼) — alpaca.markets → 가입 → 대시보드에서 API 키 발급
종목 감시 목록 — [AAPL, MSFT, NVDA, ...] 형식의 일반 리스트

흐름

장외 봉 데이터 조회

내 감시 목록 [symbols]의 어제 종가와 장 전 최신 호가를 조회하세요. % 갭을 계산하세요.✓ 복사됨

→ 표: symbol, prev_close, pre_open, gap_pct
이상 거동 표시

어느 종목이 2% 이상 갭을 벌리고 있습니까? 갭 크기로 순위를 매기세요.✓ 복사됨

→ 짧은 '주의 필요' 리스트
배경 정보 추가

각 이상 거동 종목에 대해 Alpaca 뉴스 엔드포인트에서 최신 헤드라인을 조회하세요.✓ 복사됨

→ 종목별 원인 추정 포함된 항목

결과: 1화면 분량의 일일 장 전 브리프로, 매일 동일한 형식, 수동 클릭 불필요합니다.

함정

무료 시장 데이터는 IEX만 지원되며 지연 시간이 있습니다. 호가가 브로커와 맞지 않을 수 있습니다. — 장외/장마감 분석에는 괜찮습니다. SIP 피드가 필요하면 Alpaca의 유료 데이터 플랜으로 업그레이드하세요.

함께 쓰기: notion

단순 규칙 기반 전략을 페이퍼에서 매매

👤 알고리즘 트레이딩 초심자 ⏱ ~30 min intermediate

언제 쓸까: '5일 수익률 < -3%일 때 SPY 매수, +2% 또는 5 거래일 후 매도'와 같은 규칙이 있고, 페이퍼 계좌에서 실제로 운영하려 할 때입니다.

사전 조건

페이퍼 계좌 키 설정됨 — APCA_API_BASE_URL=https://paper-api.alpaca.markets 사용
작성된 규칙 — 진입, 퇴출, 포지션 크기, 최대 손실 — 코딩 전에 모두 명시적으로 정의

흐름

계좌와 포지션 확인

내 페이퍼 계좌의 자산, 매수력, 현재 오픈 포지션을 표시하세요.✓ 복사됨

→ 깔끔한 계좌 스냅샷
오늘의 진입 조건 평가

SPY의 최근 5일 일봉을 조회하세요. 5일 수익률을 계산하세요. < -3%이고 이미 SPY를 보유하지 않은 경우, $5000 명목가로 시장가 매수 주문을 발주하세요. 그 외에는 아무것도 하지 마세요.✓ 복사됨

→ 주문 ID 또는 명시적인 '조치 없음'
오늘의 결정 기록

/trades/journal.csv에 행을 추가하세요: date, condition_met, action, order_id, fill_price.✓ 복사됨

→ 저널 행 기록됨

결과: 페이퍼 계좌에서 단순 전략의 감사 가능한 일일 운영으로, 검토할 수 있는 저널과 함께입니다.

함정

테스트 중 실계좌 키로 실수로 운영 — 시작 시 매우 명확한 확인을 유지하세요: 주문을 발주하기 전에 계좌 번호가 페이퍼 계좌와 일치하는지 확인하세요.
Claude가 어제의 포지션을 잊고 중복 매수 — 진입을 평가하기 전에 항상 현재 포지션을 조회하세요. 메모리에 의존하지 마세요.

함께 쓰기: filesystem

포트폴리오를 목표 배분으로 리밸런싱

👤 목표 배분이 정해진 개인 투자자 ⏱ ~20 min intermediate

언제 쓸까: 분기별: 60/30/10 (US/INTL/채권) 배분을 주식 수를 수동으로 계산하지 않고 목표로 되돌립니다.

사전 조건

목표 배분 정의됨 — 예: VTI 60%, VXUS 30%, BND 10%

흐름

편차 측정

내 포지션과 현재 가격을 조회하세요. 종목별 현재 비중을 목표와 비교하여 계산하세요 [목표 붙여넣기]. 편차를 $ 및 %로 표시하세요.✓ 복사됨

→ 종목별 편차 표
주문 제안

비중을 목표의 1% 이내로 맞추기 위한 최소 매수/매도 세트를 제안하세요. 예상 수수료(아마도 $0)와 예상 슬리페이지를 표시하세요.✓ 복사됨

→ 주문 계획
확인 후 실행

발주하기 전: 계획을 3줄로 요약하고 내 '예'를 기다리세요. '예' 후, 장개가 주문으로 제출하세요.✓ 복사됨

→ 주문 발주됨 (ID 포함); 자산이 목표의 1% 이내로 일치

결과: 각 주문이 발생한 이유의 기록이 포함된 깔끔한 분기별 리밸런싱입니다.

함정

과세 계좌: 매 리밸런싱이 손익을 발생시킵니다. — 신규 기여금 리밸런싱 또는 세금 고려 매도를 선호하세요. 확실하지 않으면 IRA에서만 실행하세요.

함께 쓰기: filesystem

단기 만기 풋 프리미엄을 위한 옵션 체인 스캔

👤 옵션 수익 트레이더 (현금 담보 풋 / 커버드 콜) ⏱ ~25 min advanced

언제 쓸까: 매주 소유하고 싶은 종목에서 판매할 최고의 현금 담보 풋을 찾고 싶을 때입니다.

사전 조건

옵션 활성화된 Alpaca 계좌 — 계좌 설정에서 활성화하세요. 학습용으로는 페이퍼가 작동합니다.

흐름

체인 + 그릭스 조회

[ticker]의 옵션 체인을 조회하세요. 다음 금요일 만기, 풋만, 현물 5% 이내 행사가. bid, ask, mid, delta, IV를 포함하세요.✓ 복사됨

→ 체인 표
연율화 수익률로 순위 매김

배정을 가정하여 각 행사가의 연율화 현금 수익률을 계산하세요. 델타 -0.15~-0.30으로 필터링하세요. 상위 5개 순위를 매기세요.✓ 복사됨

→ 순위가 매겨진 단축 리스트
미드에서 한도로 매도-개시 발주

#1 행사가 1계약의 미드가로 매도-개시 한도 주문을 발주하세요. GTC, 당일��.✓ 복사됨

→ 주문 ID 반환됨

결과: 보수적인 위험 선별을 포함한 반복 가능한 주간 수익 루틴입니다.

함정

소유하고 싶지 않은 기업의 풋 판매 — 엄격한 규칙: 장기 보유로 사전 승인한 10개 종목에서만 이 전략을 거래하세요.
유동성 부족 행사가와 큰 호가 스프레드 — 미드가 체결 불가능 — 순위 매기기 전에 open_interest > 500 및 spread < 5% of mid로 필터링하세요.

함께 쓰기: notion

조합

다른 MCP와 조합해 10배 효율

alpaca + notion

Notion 페이지로 제공되는 일일 장 전 브리프

감시 목록의 장 전 스캔을 실행하고 결과를 'Trading / Daily'에 Notion 페이지를 만드세요.✓ 복사됨

alpaca + filesystem

매매 저널: 모든 주문과 이유를 로컬 CSV에 추가

place_order 후에 {ts, symbol, side, qty, reason}을 /trading/journal.csv에 추가하세요.✓ 복사됨

alpaca + postgres

백테스트 전략을 위한 일일 자산 곡선 저장

매일 저녁, 오늘의 계좌 자산을 equity_curve 테이블에 INSERT하세요.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
get_account		세션의 첫 호출 — 페이퍼 vs 실계좌 확인	무료
get_positions		진입 로직 전에 현재 보유 종목 확인	무료
get_bars	symbol, timeframe, start, end, limit?	분석 및 신호를 위한 과거 OHLCV	무료 (IEX) 또는 유료 (SIP)
get_latest_quote	symbol	주문 발주 전 실시간 가격	무료
place_order	symbol, qty\|notional, side, type, time_in_force, limit_price?	새 주문 제출 (항상 페이퍼부터)	무료 (수수료 없음)
cancel_order	order_id	체결 전 오픈 주문 취소	무료
get_options_chain	underlying, expiration, side?	옵션 전략을 위한 행사가 스캔	무료

비용 및 제한

운영 비용

API 쿼터: 데이터 API에서 분당 200개 요청 (무료 티어); 거래 API는 소매 규모에서 실질적으로 제한 없습니다
호출당 토큰: 계좌/포지션: 200–500 토큰. 봉: 한도에 따라 확장합니다.
금액: Alpaca는 수수료 없습니다. SIP 피드용 유료 시장 데이터 플랜 ~$9/월; 무료 IEX 피드는 대부분의 소매 사용에 충분합니다.
팁: 실계좌에 손을 대기 전에 최소 4주 동안 모든 새 전략을 페이퍼에서 매매하세요. 무료입니다.

보안

권한, 시크릿, 파급범위

최소 스코프: 계좌 API 키 + 시크릿 — Alpaca는 하위 스코프를 지원하지 않습니다

자격 증명 저장: 환경 변수에 APCA_API_KEY_ID, APCA_API_SECRET_KEY, APCA_API_BASE_URL

데이터 외부 송신: api.alpaca.markets 또는 paper-api.alpaca.markets로의 모든 호출

절대 부여 금지: 코드 호스팅을 포함한 제3자 서비스와 실계좌 키 공유

LIVE 키는 실제 증권을 매수/매도할 수 있습니다. 전략이 검증될 때까지 PAPER URL (paper-api.alpaca.markets)을 기본값으로 사용하세요.
API 키에 2FA 없음 — 비밀번호 관리자 항목처럼 취급하고 의심 유출 후 회전하세요.

문제 해결

자주 발생하는 오류와 해결

403 forbidden.insufficient-permissions

키가 잘못된 환경 (실계좌 vs 페이퍼)입니다. APCA_API_BASE_URL을 키 쌍과 일치시키세요.

확인: curl -H 'APCA-API-KEY-ID: ...' -H 'APCA-API-SECRET-KEY: ...' $APCA_API_BASE_URL/v2/account

422 buying_power insufficient

페이퍼 계좌가 리셋되었거나 주문 규모를 현금을 초과하게 설정했습니다. get_account를 호출하고 포지션 크기를 다시 계산하세요.

Bars return empty for recent timestamp

IEX 피드는 무료 티어에서 약 15분 지연이 있으며 모든 심볼을 제공하지 않습니다. SIP를 사용하거나 기다리세요.

Order rejected: market closed

기본 TIF는 day입니다. 장 마감 주문은 time_in_force='opg' 또는 'cls'가 필요하거나 한도 주문에서 extended_hours=true로 전환하세요.

대안

Alpaca 다른 것과 비교

대안	언제 쓰나	단점/장점
Interactive Brokers MCP	국제 시장이나 선물이 필요할 때	더 복잡한 인증 (게이트웨이 앱 필수); 학습 곡선
Polygon.io MCP	시장 데이터만 필요하고 매매는 하지 않을 때	주문 실행 없음; 완전한 커버리지에는 유료

Alpaca

왜 쓰나요

핵심 기능

라이브 데모

실제 사용 모습

설치

클라이언트 선택

사용 사례

실전 활용법: Alpaca

감시 목록의 일일 장 전 브리프 생성

사전 조건

흐름

함정

단순 규칙 기반 전략을 페이퍼에서 매매

사전 조건

흐름

함정

포트폴리오를 목표 배분으로 리밸런싱

사전 조건

흐름

함정

단기 만기 풋 프리미엄을 위한 옵션 체인 스캔

사전 조건

흐름

함정

조합

다른 MCP와 조합해 10배 효율

도구

이 MCP가 노출하는 것

비용 및 제한

운영 비용

보안

권한, 시크릿, 파급범위

문제 해결

자주 발생하는 오류와 해결

대안

Alpaca 다른 것과 비교

더 보기

리소스