How do I use sj-trading-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@sj-trading-mcp 查詢台積電股票即時價格" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

sj-trading-mcp

by scorpio-su

Overview Schema Related Servers Score Discussions

Python

Remote

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

Related MCP server: Shioaji MCP Server

設定金鑰

複製範本後填入真實值：

# 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。

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/scorpio-su/sj-trading-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

sj-trading-mcp

專案結構

設定金鑰

Docker 啟動（推薦）

整合 Claude Code

MCP 工具清單

連線管理

股票交易

期貨交易

選擇權交易

選擇權策略（多腿組合）

網格策略（Grid）

馬丁格爾策略（Martingale）

行情資料

帳務查詢

核心模組說明

CredentialsLoader（src/core/credentials.py）

ApiClient（src/core/api_client.py）

Trading 模組（src/trading/）

Market 模組（src/market/）

Accounting 模組（src/accounting/）

OptionStrategy 模組（src/option_strategy/）

策略模組（src/grid_martingale_strategy/）

執行測試

環境變數

Design Principles

⚠️ 注意事項

Maintenance

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API

`CredentialsLoader`（`src/core/credentials.py`）

`ApiClient`（`src/core/api_client.py`）

Trading 模組（`src/trading/`）

Market 模組（`src/market/`）

Accounting 模組（`src/accounting/`）

OptionStrategy 模組（`src/option_strategy/`）

策略模組（`src/grid_martingale_strategy/`）