快速开始

从安装到第一次调用，大约五分钟。

更新于 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 授权即可。下单、改单、撤单请用本地客户端。

遇到问题？

把截图和客户端版本发给我们，我们会帮你排查。

联系支持