sj-trading-mcp

永豐 Shioaji MCP Server，讓 Claude（或任何 MCP 客戶端）能直接操作台灣股票、期貨與選擇權交易，並查詢即時行情與帳務資料。
遵循 OOP + Clean Code（Uncle Bob） 原則，預設執行於 simulation=True 模擬環境。

---

專案結構

sj_trading-mcp/
├── config/
│   ├── credentials.json.example  ← 金鑰範本（JSON 格式）
│   ├── credentials.txt.example   ← 金鑰範本（key=value 格式）
│   ├── credentials.json          ← 實際金鑰（git ignored）
│   └── credentials.txt           ← 實際金鑰（git ignored）
├── src/
│   ├── core/
│   │   ├── credentials.py        ← 金鑰載入器（支援 .json / .txt 自動判斷）
│   │   └── api_client.py         ← Shioaji 連線封裝（支援 with 語法）
│   ├── market/
│   │   ├── stock_market.py       ← 股票行情：快照、K 線、Tick、資券、券源
│   │   ├── futures_market.py     ← 期貨行情：歷史 K 線（含連續合約）
│   │   └── market_info.py        ← 市場資訊：掃描器排行、處置股、注意股
│   ├── accounting/
│   │   ├── stock_account.py      ← 股票帳務：餘額、交易額度、交割資訊
│   │   ├── futures_account.py    ← 期貨帳務：保證金查詢
│   │   └── common_account.py     ← 跨帳戶：損益查詢、持倉明細
│   ├── trading/
│   │   ├── stock_trader.py       ← 股票交易：下單、改單、市價單、查持倉
│   │   ├── futures_trader.py     ← 期貨交易：開平倉、改單、查持倉
│   │   └── options_trader.py     ← 選擇權交易：下單、刪單、查持倉
│   ├── option_strategy/
│   │   ├── _types.py             ← 資料模型：Action / Right / InstrumentType / Leg / Strategy
│   │   ├── _pure_option.py       ← 純選擇權策略（45 種）
│   │   ├── _stock_legged.py      ← 含股票腿策略（6 種）
│   │   ├── _future_legged.py     ← 含期貨腿策略（7 種）
│   │   └── strategies.py         ← 策略總表 STRATEGIES + get_strategy()
│   └── grid_martingale_strategy/
│       ├── __init__.py           ← 對外 export 兩策略 + factories
│       ├── base/                 ← BaseStrategy、TradeJournal、RiskPolicy
│       ├── grid/                 ← GridStrategy、GridConfig、build_grid_strategy
│       ├── martingale/           ← MartingaleStrategy、MartingaleConfig、build_martingale_strategy
│       ├── adapters/             ← MarketAdapter + stock/futures 實作
│       ├── risk/                 ← GridRisk、MartingaleStockRisk、MartingaleFuturesRisk
│       ├── config/               ← 向後相容 re-export（grid/、martingale/ 為 canonical）
│       └── _types.py             ← 共用 enum / dataclass
├── tests/
│   ├── test_stock.py             ← 股票模擬測試
│   ├── test_futures.py           ← 期貨模擬測試
│   ├── test_market.py            ← 行情資料模擬測試
│   ├── test_accounting.py        ← 帳務查詢模擬測試
│   └── test_options.py           ← 選擇權模擬測試
├── .claude/
│   └── settings.json             ← Claude Code MCP 設定
├── server.py                     ← MCP Server 主程式
├── main.py                       ← 快速端對端測試（含 grid / martingale）
├── Dockerfile
├── pyproject.toml
└── requirements.txt

---

設定金鑰

複製範本後填入真實值：

# JSON 格式
cp config/credentials.json.example config/credentials.json

# 或 txt 格式
cp config/credentials.txt.example config/credentials.txt

僅行情 / 股票下單（credentials.json，不需 CA）：

{
  "api_key": "YOUR_API_KEY",
  "secret_key": "YOUR_SECRET_KEY"
}

期貨 / 選擇權下單須填寫 CA 憑證欄位（模擬與真實模式皆需）：

{
  "api_key": "YOUR_API_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "ca_path": "config/ca/YOUR_CA.pfx",
  "ca_password": "YOUR_CA_PASSWORD",
  "person_id": "YOUR_PERSON_ID"
}

CA 欄位存在時，ApiClient 在連線後立即啟動憑證（無論模擬或真實模式）。
TAIFEX（期貨交易所）即使在模擬環境也需要帳戶層級的 CA 簽署才能接受委託。

---

Docker 啟動（推薦）

# 第一次 build
docker build -t sj-trading-mcp .

# 啟動（模擬模式）
docker run -d \
  --name sj-trading-mcp \
  -p 127.0.0.1:9090:9090 \
  -v ./config:/app/config:ro \
  -v ./logs:/app/logs \
  --restart unless-stopped \
  sj-trading-mcp

# 真實下單模式
docker run -d \
  --name sj-trading-mcp \
  -p 127.0.0.1:9090:9090 \
  -v ./config:/app/config:ro \
  -v ./logs:/app/logs \
  -e SJ_SIMULATION=false \
  --restart unless-stopped \
  sj-trading-mcp

停止 / 重啟：

docker stop sj-trading-mcp
docker start sj-trading-mcp

查 log：

docker logs -f sj-trading-mcp
# 或查 log 檔
cat logs/server.log

---

整合 Claude Code

.claude/settings.json 已預設配置，在此專案目錄下開啟 Claude Code 即自動載入。

CLI 加入（專案範圍）：

claude mcp add sj-trading --transport http http://127.0.0.1:9090/mcp --scope project

---

MCP 工具清單

連線管理

工具	說明
connect_api(simulation)	連線 API（simulation=true 預設模擬，false 真實下單）
disconnect_api()	登出斷線
connection_status()	查詢連線狀態

股票交易

工具	說明
stock_buy(symbol, price, quantity)	整股限價買進（ROD）
stock_sell(symbol, price, quantity)	整股限價賣出（ROD）
stock_market_buy(symbol, quantity)	整股市價買進（MKT + IOC）
stock_market_sell(symbol, quantity)	整股市價賣出（MKT + IOC）
stock_buy_odd(symbol, price, quantity, intraday)	零股買進
stock_sell_odd(symbol, price, quantity, intraday)	零股賣出
stock_margin_buy(symbol, price, quantity)	融資買進
stock_margin_sell(symbol, price, quantity)	融資賣出／還券
stock_short_sell(symbol, price, quantity)	融券賣出
stock_short_cover(symbol, price, quantity)	融券回補
stock_cancel(order_id)	刪除委託單
stock_update_order(order_id, price, qty)	改價或減量（二選一）
stock_list_trades()	查詢所有委託紀錄
stock_positions()	查詢股票持倉
stock_contract_info(symbol)	查詢合約基本資訊

期貨交易

工具	說明
futures_open_long(symbol, price, quantity)	開多倉（Buy + OCType.New）
futures_open_short(symbol, price, quantity)	開空倉（Sell + OCType.New）
futures_close_long(symbol, price, quantity)	平多倉（Sell + OCType.Cover）
futures_close_short(symbol, price, quantity)	平空倉（Buy + OCType.Cover）
futures_cancel(order_id)	刪除委託單
futures_update_order(order_id, price, qty)	改價或減量
futures_positions()	查詢期貨持倉
futures_contract_info(symbol)	查詢合約基本資訊

選擇權交易

工具	說明
options_buy(symbol, price, quantity, octype)	買進選擇權（LMT + ROD）
options_sell(symbol, price, quantity, octype)	賣出選擇權（LMT + ROD）
options_cancel(order_id)	刪除委託單
options_positions()	查詢選擇權／期貨持倉
options_contract_info(symbol)	查詢合約資訊（到期月、履約價、Call/Put）

symbol 格式：TXO20260620200C（商品代碼 + YYYYMMDD + 履約價 + C/P）
octype："Auto"（預設）/ "NewPosition"（新倉）/ "Cover"（平倉）

選擇權策略（多腿組合）

工具	說明
strategy_list()	列出所有可用策略（純選擇權 45 種、含股票腿 6 種、含期貨腿 7 種，共 58 種）
strategy_info(strategy_id)	查詢策略腿部結構（方向、標的類型、Put/Call、履約價位、口數）
strategy_execute(strategy_id, leg_symbols, leg_prices, base_qty)	執行多腿策略，逐腿送出委託

使用流程：strategy_list() → strategy_info() 確認腿部順序 → strategy_execute() 下單
leg_symbols / leg_prices 長度須與策略腿數一致；base_qty 為口數乘數（預設 1）

網格策略（Grid）

工具	說明
grid_create(market_type, symbol, upper_price, lower_price, grid_count, grid_unit_qty, ...)	建立純網格策略，回傳 grid-N
grid_start(strategy_id)	啟動（idle → running）
grid_stop(strategy_id)	停止行情訂閱
grid_status(strategy_id)	查詢狀態（strategy_type=grid、格位數、triggered_levels）
grid_rebalance(strategy_id)	重新對齊格位
grid_destroy(strategy_id)	停止並移除
grid_list()	列出所有網格策略

使用流程：grid_create(...) → grid_start('grid-1') → grid_status(...) → grid_stop / grid_destroy
grid_create 不再包含馬丁參數；grid_mode："arithmetic" / "geometric"；direction："LONG" / "SHORT"（僅期貨）

馬丁格爾策略（Martingale）

工具	說明
martingale_create(market_type, symbol, mart_multiplier, mart_trigger_pct, mart_max_times, mart_initial_qty, mart_take_profit_pct, ...)	建立純馬丁策略，回傳 mart-N
martingale_start(strategy_id)	啟動（idle → running）
martingale_stop(strategy_id)	停止行情訂閱
martingale_status(strategy_id)	查詢狀態（layer_count、avg_cost、frozen、liquidating）
martingale_destroy(strategy_id)	停止並移除
martingale_list()	列出所有馬丁策略

使用流程：martingale_create(...) → martingale_start('mart-1') → martingale_status(...) → martingale_stop / martingale_destroy
qty_mode："multiply" / "linear"；策略 ID 前綴為 mart-（與網格的 grid- 分開管理）

網格與馬丁為完全獨立策略：grid/ 與 martingale/ 互不 import，可各自建立、各自運行。原 GridMartingaleStrategy / build_strategy 已移除。

行情資料

工具	說明
stock_snapshot(symbols)	即時快照（最多 500 檔，含現價 / 漲跌 / 量）
stock_kbars(symbol, start, end)	歷史 K 棒（1 分鐘），start/end 格式 YYYY-MM-DD
stock_ticks(symbol, date, query_type, ...)	歷史 Tick，query_type: "AllDay" / "RangeTime" / "LastCount"
stock_credit_enquiries(symbols)	個股融資融券餘額
stock_short_sources(symbols)	可借券來源與張數
futures_kbars(symbol, start, end)	期貨歷史 K 棒（支援連續合約 TXFR1/TXFR2）
market_scanners(scanner_type, ascending, count)	市場排行掃描器
market_punish()	處置股清單
market_notice()	注意股清單

scanner_type 可用值："ChangePercentRank" / "ChangePriceRank" / "DayRangeRank" / "VolumeRank" / "AmountRank"

帳務查詢

工具	說明
account_balance()	股票帳戶可用餘額
stock_trading_limits()	股票交易額度（含融資 / 融券額度）
list_settlements()	交割資訊（T / T+1 / T+2）
futures_margin()	期貨保證金（可用保證金、風險指標等）
list_profit_loss(account_type, begin_date, end_date)	已實現損益，按日期區間查詢
list_position_detail(account_type, detail_id)	持倉明細（含成本價、進場日）

account_type："stock" 或 "futopt"

---

核心模組說明

CredentialsLoader（src/core/credentials.py）

• 單一職責：只負責讀取與驗證金鑰
• 以 frozen=True dataclass 保存，防止意外修改
• 缺少欄位時拋出含明確說明的 KeyError

ApiClient（src/core/api_client.py）

• 封裝 login / logout 流程
• 支援 with 語法，確保 logout 必然執行
• 未連線前訪問 .api 屬性拋出 RuntimeError
• 所有模組共用同一 ApiClient 實例（避免超過 5 connections/person ID 上限）
• 若 credentials 含 CA 欄位，則模擬與真實模式皆啟動憑證（期貨 / 選擇權下單需要）

Trading 模組（src/trading/）

模組	類別	主要方法
stock_trader.py	StockTrader	buy / sell / market_buy / market_sell / buy_odd / sell_odd / margin_buy / short_sell / cancel / update_order / list_trades / list_positions
futures_trader.py	FuturesTrader	open_long / open_short / close_long / close_short / cancel / update_order / list_positions
options_trader.py	OptionsTrader	buy / sell / cancel / contract_info / list_positions

Market 模組（src/market/）

模組	類別	主要方法
stock_market.py	StockMarket	stock_snapshot / stock_kbars / stock_ticks / credit_enquiries / short_stock_sources
futures_market.py	FuturesMarket	futures_kbars
market_info.py	MarketInfo	market_scanners / market_punish / market_notice

Accounting 模組（src/accounting/）

模組	類別	主要方法
stock_account.py	StockAccount	account_balance / trading_limits / list_settlements
futures_account.py	FuturesAccount	futures_margin
common_account.py	CommonAccount	list_profit_loss / list_position_detail

OptionStrategy 模組（src/option_strategy/）

純資料驅動的多腿策略定義層，不依賴 Shioaji API，可獨立測試。

類型	策略數量	範例
純選擇權（_pure_option.py）	45 種	long_call / straddle / iron_condor / calendar_call_spread / double_diagonal …
含股票腿（_stock_legged.py）	6 種	covered_call / protective_put / collar / cash_secured_put …
含期貨腿（_future_legged.py）	7 種	long_synthetic_future / protective_futures_put / futures_collar …

• Strategy — frozen dataclass，持有 strategy_id 與 legs: tuple[Leg, ...]
• OptionLeg / StockLeg / FutureLeg — 各腿類型，描述 action（BUY/SELL）、qty、right、strike、expiry
• get_strategy(strategy_id) — 依 ID 取得策略，找不到時拋出 KeyError
• server.py 使用此模組實作 strategy_list / strategy_info / strategy_execute 三個 MCP 工具

策略模組（src/grid_martingale_strategy/）

網格與馬丁已拆分為兩個獨立策略，共用 base/ 骨架（Template Method）與 adapters/ 基礎設施。
grid/ 與 martingale/ 互不 import，各自持有專屬 config 與 position book。

子模組	職責
base/	BaseStrategy、TradeJournal、RiskPolicy（GridRiskPolicy / MartingaleRiskPolicy）
grid/	GridStrategy、GridConfig、GridPositionBook、build_grid_strategy()
martingale/	MartingaleStrategy、MartingaleConfig、LayerBook、build_martingale_strategy()
adapters/	MarketAdapter + stock/futures 實作
risk/	GridRisk、MartingaleStockRisk、MartingaleFuturesRisk

對外 API（__init__.py）：

符號	說明
GridStrategy / build_grid_strategy	純網格
MartingaleStrategy / build_martingale_strategy	純馬丁
GridConfig / MartingaleConfig	各自設定 dataclass
MarketType / Direction / GridMode / QtyMode / StrategyState	共用列舉

MartingaleConfig 第一個參數為 symbol（拆分後新增）。
舊路徑 config/grid_config.py、config/martingale_config.py 仍 re-export，canonical 位置分別在 grid/、martingale/。

from src.grid_martingale_strategy import (
    build_grid_strategy, build_martingale_strategy,
    GridConfig, MartingaleConfig,
    MarketType, Direction, GridMode, QtyMode,
)

grid_cfg = GridConfig("2330", 1000.0, 800.0, 10, GridMode.ARITHMETIC, grid_unit_qty=1)
grid = build_grid_strategy(MarketType.STOCK, client, grid_cfg)
grid.initialize(); grid.start()

mart_cfg = MartingaleConfig("2330", 2.0, -0.05, 3, 2, 0.03, QtyMode.MULTIPLY)
mart = build_martingale_strategy(MarketType.STOCK, client, mart_cfg)
mart.initialize(); mart.start()

---

執行測試

所有測試皆在 simulation=True 模擬模式下執行，不會觸發真實交易。

uv run python tests/test_stock.py
uv run python tests/test_futures.py
uv run python tests/test_market.py
uv run python tests/test_accounting.py
uv run python tests/test_options.py

測試檔	必要條件	備註
test_stock.py	僅 api_key / secret_key	股票模擬完整測試
test_futures.py	CA 憑證（建議）	無 CA 或帳戶未在 TAIFEX 簽署時，下單步驟自動跳過並顯示警告
test_market.py	僅 api_key / secret_key	行情查詢不需 CA
test_accounting.py	僅 api_key / secret_key	帳務查詢不需 CA
test_options.py	僅 api_key / secret_key	合約與持倉查詢；自動尋找當前有效 TXO 合約

main.py 快速端對端測試（含 Grid / Martingale）：

python main.py                  # 全部測試（stock + futures + options + grid + martingale）
python main.py stock            # 只測股票
python main.py futures          # 只測期貨
python main.py options          # 只測選擇權
python main.py grid             # 只測純網格（現股）
python main.py grid_futures     # 只測純網格（期貨）
python main.py martingale       # 只測純馬丁（現股）
python main.py martingale_futures  # 只測純馬丁（期貨）

---

環境變數

變數	預設	說明
SJ_SIMULATION	true	false 切換真實下單
MCP_HOST	0.0.0.0	server 監聽 host
MCP_PORT	9090	server 監聽 port
LOG_DIR	logs	log 檔目錄

---

Design Principles

• SRP：每個 class 只負責一件事（交易 / 行情 / 帳務明確分層）
• 依賴注入：所有模組接收 ApiClient，不直接建立連線
• 共用連線：_Session 管理單一 ApiClient 生命週期，防止超過連線數上限
• 語意方法名：open_long / close_short 優於 place_order(octype=...)
• 不回傳 None：錯誤以例外表達（ValueError / RuntimeError）
• 非同步行情與帳務：市場資料與帳務工具使用 async + run_in_executor 避免卡頓

---

⚠️ 注意事項

• 預設 SJ_SIMULATION=true，絕對不會動用真實帳戶。
• 期貨 / 選擇權委託（含模擬模式）需在 credentials 填入 CA 欄位，且帳戶需已在 TAIFEX 完成 CA 簽署。
• 切換真實模式前，請確認 CA 欄位（ca_path、ca_password、person_id）正確填寫。
• 真實下單操作不可逆，請在確認合約、價格、數量後再執行。
• 行情查詢限速：50 req / 5s；帳務查詢限速：25 req / 5s。