Avanza-MCP

Avanza 포트폴리오 모니터링, 일반 매수/매도 주문, 손절매 관리, MCP 통합 및 모의 투자를 위한 단일 스크립트 CLI + Textual TUI입니다.

자격 증명은 런타임에 입력하라는 메시지가 표시됩니다:

• 사용자 이름: --username으로 전달하지 않는 한 표시되는 프롬프트

• 비밀번호: 마스킹됨

• 현재 TOTP 코드: 마스킹됨

또는 --onepassword-item ITEM과 선택 사항인 --onepassword-vault VAULT를 전달하여 1Password CLI(op)를 통해 Avanza 사용자 이름, 비밀번호 및 현재 TOTP 코드를 읽을 수 있습니다. TUI에는 일치하는 Login with 1Password 경로가 있습니다. 이 도구는 이러한 비밀 정보를 저장하지 않으며, op가 로컬 1Password 앱을 통해 액세스 권한을 승인하도록 요청합니다.

현재 TOTP 코드는 설치된 라이브러리 버전에서 예상하는 필드 이름인 totpToken으로 avanza-api에 전달됩니다.

설정

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
chmod +x scripts/verify.sh .githooks/pre-commit .githooks/pre-push
git config core.hooksPath .githooks

언제든지 전체 품질 게이트를 실행하세요:

scripts/verify.sh

명령어

콘솔 명령어는 원시 API 페이로드가 아닌 사람이 읽을 수 있는 Rich 테이블과 요약을 출력합니다.

계정 개요 보기:

python avanza_cli.py accounts

포트폴리오 요약 보기:

python avanza_cli.py portfolio summary

상세 포트폴리오 포지션 보기:

python avanza_cli.py portfolio positions

주식/주문 장부 검색:

python avanza_cli.py search-stock "VOLV B"

활성 손절매 주문 나열:

python avanza_cli.py stoploss list

트레일링/글라이딩 매도 손절매 드라이런(Dry-run):

python avanza_cli.py stoploss set \
  --account-id ACCOUNT_ID \
  --order-book-id ORDER_BOOK_ID \
  --trigger-type follow-upwards \
  --trigger-value 5 \
  --trigger-value-type % \
  --order-type sell \
  --order-price 1 \
  --order-price-type % \
  --volume 10

드라이런 출력을 검토한 후 --confirm을 추가하여 실제로 주문을 실행하세요. --valid-until이 생략되면 avanza_cli는 자동으로 현재 허용되는 가장 긴 날짜(오늘 + 90일)를 사용합니다. --order-valid-days가 생략되면 avanza_cli는 현재 Avanza 안전 기본값(8)을 사용합니다.

손절매 주문 삭제 드라이런:

python avanza_cli.py stoploss delete \
  --account-id ACCOUNT_ID \
  --stop-loss-id STOP_LOSS_ID

--confirm을 추가하여 실제로 삭제하세요.

미체결 일반 주문 나열:

python avanza_cli.py orders list

일반 매수/매도 주문 드라이런:

python avanza_cli.py orders set \
  --account-id ACCOUNT_ID \
  --order-book-id ORDER_BOOK_ID \
  --order-type buy \
  --price 100 \
  --valid-until 2026-05-28 \
  --volume 10 \
  --condition normal

주문 삭제 드라이런:

python avanza_cli.py orders delete \
  --account-id ACCOUNT_ID \
  --order-id ORDER_ID

Textual TUI

동일한 스크립트에서 터미널 UI를 실행하세요:

python avanza_cli.py tui

TUI는 비밀번호 및 TOTP 입력을 마스킹하고, 성공적으로 로그인한 후 해당 필드를 지우며, 로그인 화면을 숨깁니다. 1Password 항목 이름/ID와 선택적 볼트를 입력한 다음 Login with 1Password를 사용하여 1Password 승인 후 로컬 op CLI가 사용자 이름, 비밀번호 및 TOTP를 가져오도록 할 수 있습니다. 모의 주문이나 실거래 주문을 생성하지 않고 주문 요청을 검증하고 기록하려면 먼저 Review Only를 사용하세요.

로그인 후에는 총 가치가 가장 큰 계정이 기본적으로 선택됩니다. 상단 패널은 계정 지표를 색상이 지정된 카드로 그룹화하고, 작업 버튼을 함께 유지하며, 실시간 시계와 평일 OMXS 개장/폐장 카운트다운을 표시합니다. P/L 지표는 1D P/L, 1W P/L, 1M P/L, 1Y P/L, Total P/L 순으로 순환하며, SEK 및 % 값은 별도의 색상으로 표시됩니다. 메인 테이블은 선택한 계정의 주식과 일일 변동, 수익 상태, 별도의 헤더 행, 실시간 시세 표시기를 보여줍니다(실시간은 녹색 점, 지연 또는 미해결 상태는 노란색 점). 주문 티켓은 주식 이름, 티커 또는 ISIN으로 입력하는 즉시 검색되므로 현재 보유 종목 거래뿐만 아니라 신규 포지션 오픈도 지원합니다. 하단 테이블은 선택한 계정의 손절매 및 미체결 주문을 보여주며, 트리거 및 가격 값은 SEK 또는 %로 표시됩니다. 취소 열은 보호된 취소 티켓을 엽니다. 매수/매도 측 셀은 녹색/빨간색으로 색상 코딩되어 있습니다. 테이블 열 헤더를 클릭하여 해당 열을 기준으로 정렬하고, 같은 헤더를 다시 클릭하여 정렬 순서를 반전시킬 수 있습니다. 테이블 사이의 가로 구분선, Active Trades 옆의 세로 구분선 또는 주문/손절매 티켓의 왼쪽 가장자리를 드래그하여 창 크기를 조정하세요. 포지션 및 주문 상태는 5초마다 실시간으로 새로 고쳐집니다.

MCP 서버 등록 및 실행

이 프로젝트는 python avanza_cli.py mcp(stdio 전송)를 통해 MCP를 노출합니다.

1) TUI 시작 및 인증

python avanza_cli.py tui

로그인한 다음 TUI에서 MCP 체크박스를 활성화하세요. 그러면 로컬호스트 브리지가 시작되고 .avanza_mcp_session.json이 작성됩니다.

2) Codex/Codex CLI에 MCP 서버 등록

~/.codex/config.toml에 다음을 추가하세요:

[mcp_servers.avanza-mcp]
command = "python"
args = ["/ABSOLUTE/PATH/TO/avanza_cli.py", "mcp"]

로컬 avanza_cli.py의 절대 경로를 사용하세요.

3) MCP 클라이언트에서 실행

등록 후 Codex 또는 Codex CLI를 시작/새로 고침하세요. 다음이 실행됩니다:

python avanza_cli.py mcp

MCP 프록시는 로컬호스트 브리지를 통해 인증된 TUI 세션으로 도구 호출을 전달합니다. MCP는 읽기 전용으로 시작됩니다. 실시간 변경을 위해 TUI에서 Live R/W를 활성화하세요. 실시간 손절매/주문 배치, 편집, 교체 또는 삭제를 수행하려면 MCP 인수에 confirm: true가 포함되어야 합니다. MCP 활동은 오른쪽 하단의 로그 콘솔에 표시됩니다.

4) ChatGPT 데스크톱 참고 사항

ChatGPT 개발자 모드는 현재 SSE 또는 스트리밍 HTTP를 통한 원격 MCP 앱/커넥터를 예상하므로 이 로컬 stdio 프록시를 직접 등록할 수 없습니다.

자동 트레이딩 실험을 위해서는 폴링 도구로 avanza_live_snapshot을 사용하세요. 이는 의사 결정이 가능한 계정 스냅샷을 반환하며 5초마다 호출해도 안전합니다. 모의 투자는 avanza_paper_stoploss_set, avanza_paper_order_set, avanza_paper_orders, avanza_paper_cancel을 통해 읽기 전용 MCP 모드에서 사용할 수 있습니다. 모의 투자 상태는 .avanza_paper_session.json에 저장되며 Avanza 주문을 생성하지 않습니다. TUI의 Paper 체크박스는 기본적으로 켜져 있으며, 켜져 있는 동안 주문 및 손절매 양식 제출 버튼은 로컬 모의 주문을 생성합니다. 실거래 Avanza 배치를 사용하려는 경우에만 Paper를 끄세요(이 경우에도 PLACE를 입력해야 함). 일반 실거래 매수/매도 주문도 avanza_order_set 및 avanza_order_delete를 통해 노출되며, MCP R/W 모드와 confirm: true에 의해 제어됩니다.

TUI 세션은 avanza-cli/logs/ 아래에 구조화된 JSONL 로그를 작성합니다: 타임스탬프가 찍힌 세션 로그와 지속적인 app.jsonl, mcp.jsonl, trading.jsonl 파일이 생성됩니다.

안전성

이 프로젝트는 비공식 avanza-api 패키지를 사용합니다. stoploss list와 드라이런으로 시작하세요. 의미 있는 주문에 사용하기 전에 매우 작은 규모로 Avanza의 % 및 글라이딩 손절매 필드에 대한 실시간 해석을 검증하세요.

크레딧

제작자: Hamid Kashfi 및 Codex (OpenAI).

이 프로젝트는 fama93의 Python avanza-api 라이브러리를 기반으로 합니다:

• PyPI: avanza-api

• 소스: github.com/fhqvst/avanza