Getting Started

快速開始

本頁提供最小但完整的安裝路徑：建立隔離環境、安裝套件與官方 SDK、設定認證、啟動 MCP Server，最後以唯讀工具確認連線。

1. 先備條件

• Python 3.10–3.13。
• 可使用富邦證券 Trade API 的帳戶。
• 有效的 PFX 憑證；API-Key 登入亦需要由金鑰管理頁匯出的網頁憑證。
• 對應平台的 fubon_neo 2.2.8 wheel。
• 一個支援 MCP 的 Host，例如 VS Code。

2. 建立開發環境

Windows PowerShell：

git clone https://github.com/Mofesto/fubon-api-mcp-server.git
Set-Location fubon-api-mcp-server
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

若 fubon_neo 尚未安裝，請依平台安裝儲存庫 wheels/ 內的 2.2.8 wheel，例如：

python -m pip install .\wheels\fubon_neo-2.2.8-cp37-abi3-win_amd64.whl

Linux x86_64、macOS Intel 與 Apple Silicon 均有各自 wheel；不要跨平台安裝。

3. 建立本機設定

Copy-Item .env.example .env

選擇下列其中一種認證。

傳統登入：

FUBON_USERNAME=<YOUR_PERSONAL_ID>
FUBON_PASSWORD=<YOUR_PASSWORD>
FUBON_PFX_PATH=C:\secure\path\certificate.pfx
FUBON_PFX_PASSWORD=<YOUR_CERT_PASSWORD>
FUBON_DATA_DIR=D:\FubonMcpData
FUBON_MCP_TRANSPORT=stdio

API-Key 登入：

FUBON_USERNAME=<YOUR_PERSONAL_ID>
FUBON_API_KEY=<YOUR_API_KEY>
FUBON_PFX_PATH=C:\secure\path\web-certificate.pfx
FUBON_PFX_PASSWORD=<YOUR_CERT_PASSWORD>
FUBON_DATA_DIR=D:\FubonMcpData
FUBON_MCP_TRANSPORT=stdio

FUBON_API_KEY 一旦存在，啟動流程會優先使用 API-Key 登入。完整欄位與 transport 請見 設定與認證。

4. 啟動 Server

推薦使用模組入口：

python -m fubon_api_mcp_server.server

安裝套件後亦可使用 console script：

fubon-api-mcp-server

成功啟動前，Server 會依序登入、呼叫 sdk.init_realtime()、取得 stock／futopt REST clients、註冊主動回報 callback，再啟動選定的 MCP transport。

Note

stdio 模式的標準輸出是 MCP 通訊通道。不要在啟動器中混入會寫入 stdout 的自訂訊息；日誌應透過既有 logging 路徑輸出。

5. 連接 MCP Host

VS Code 使用者可安裝 Extension mofesto.fubon-api-mcp-server，或在使用者層級 mcp.json 設定 stdio server。完整範例請見 MCP Client 設定。

6. 唯讀驗證順序

初次設定請只執行查詢：

1. get_account_info：確認登入成功並取得可用帳戶。
2. get_intraday_quote：查詢已知商品的即時報價。
3. historical_candles：確認 REST market data 與本地 SQLite 快取可用。
4. get_inventory：以明確帳戶確認 accounting API。
5. get_event_reports：檢查目前 server process 收到的連線事件。

MCP tool 呼叫的業務參數要放在 args 內。例如：

{
  "args": {
    "symbol": "2330"
  }
}

不要用 place_order 作為安裝 smoke test。自動化測試也不得送出真實訂單。

7. 開發環境自我檢查

python -m pip check
python -m pytest tests/test_mcp_v2_protocol.py -v
python -m pytest tests/test_account_service.py -v

完整品質檢查請見 開發與測試。

下一步

• 工具沒有出現：閱讀 故障排除。
• 要呼叫行情：閱讀 市場資料工具。
• 要實作交易流程：先閱讀 交易工具 的寫入安全章節。