快速開始

由安裝到第一次呼叫，大約五分鐘。

更新於 2026-11-04

usmartsg-mcp 係本地運行嘅交易 MCP Server：喺你自己部電腦跑，用你本機嘅授權，代 AI 客戶端執行訂單查詢、落單前預檢、落單同改單。

usmartsg-mcp 已發布到 PyPI（Apache-2.0，現時 1.1.0）。裝好後 11 個工具預設全部可用，包括落單同改單，唔需要額外開關。

開始之前

已開戶並開通 uSMART SG OpenAPI 權限嘅賬戶
Python 3.10–3.13 與 uv
一個支援 MCP 嘅客戶端：Claude Code、Cursor、Codex、Kiro，或者 Claude 嘅自訂連接器
唔需要自己申請 App ID 或密鑰：授權喺瀏覽器用 uSMART 賬戶完成

第一步：加入客戶端

本地客戶端用一行指令加入（以 Claude Code 為例）：

terminal

bash

claude mcp add usmart -- uvx --from usmartsg-mcp==1.1.0 usmartsg-mcp

Cursor、Codex、Kiro 嘅設定見各自嘅接入頁。首次啟動時，服務會喺 ~/.usmart 自動生成 config.json，唔使手寫。

第二步：授權

喺對話裡面叫助手呼叫 oauth_login，瀏覽器會打開 uSMART 授權頁；同意後呼叫 oauth_login_status 兌換令牌。之後令牌自動續期。

喺對話裡面

text

oauth_login
oauth_login_status

第三步：驗證

喺對話裡面

text

check_trade_credentials
list_today_orders

check_trade_credentials 只讀本地檔案、唔聯網、唔落單，回傳嘅憑證資料全部脫敏。list_today_orders 驗證查詢鏈路；確認鏈路之後就可以落單，每筆都會先問你確認。

本地檔案與預設設定

所有授權資料只放喺本機 ~/.usmart，唔會隨包分發，亦唔會作為工具參數傳俾模型。

~/.usmart

text

~/.usmart/
├── config.json          # 首次運行自動生成，通常唔使改
├── oauth_session.json   # 授權成功後自動生成（600）
├── credentials.json     # 可選：賬戶開啟交易密碼校驗時，只寫 tradePassword
└── audit/               # 寫入操作審計流水

設定項	生產（預設）	UAT（USMART_ENV=uat）
baseUrl	https://open2-jy.usmartsg.com	https://open2-jy-uat.usmartsg.com
auth.oauth.baseUrl	https://jy.usmartsg.com	https://jy-uat.usmartsg.com
auth.oauth.clientId	ai-agent	agent-uat
auth.oauth.redirectUri	http://localhost:5100/callback	同左
auth.oauth.scopes	order:all	同左

redirectUri 請用 localhost，127.0.0.1 形式會被 uSMART 網關拒絕。macOS / Linux 建議收緊目錄權限：

bash

mkdir -p ~/.usmart && chmod 700 ~/.usmart

喺 Claude 使用連接器

唔想裝 Python 嘅話，可以喺 Claude 新增自訂連接器，只做訂單查詢與落單前預檢：

Settings → Connectors → Add custom connector

text

https://openapi.usmartglobal.com/mcp

認證揀 OAuth，喺瀏覽器完成 uSMART 授權就得。落單、改單、撤單請用本地客戶端。

遇到問題？

把截圖和客戶端版本發給我們，我們會幫你排查。

聯絡支援