usmartsg-mcp

# usmartsg-mcp 面向 [uSmart SG](https://www.usmart.sg) OpenAPI 用户的本地交易 MCP Server。它通过标准 MCP Tools 向 Kiro、Codex、Claude Desktop、Cursor 等客户端提供订单预检、订单查询、下单和 改单能力。 本项目在本地以 stdio 运行：每位用户使用自己的 uSmart 账户和授权，凭证只保存在本机， 不随 PyPI 包分发，也不通过 MCP 工具参数传递。 > 当前仅支持 SG。服务可连接生产交易账户；默认即注册下单/改单工具，调用时可能产生真实资金交易。 > 本工具不提供投资建议，所有委托均由账户所有者负责。 ## 主要特性 - 基于官方 MCP Python SDK，默认使用 stdio 传输； - 使用 OAuth2 授权码 + PKCE：在浏览器用 uSmart 账户授权，令牌自动续期，无需自行申请 App ID 或密钥； - 首次运行自动生成 OAuth2 配置，装完即可授权，无需手写 JSON； - 凭证默认存放在 `~/.usmart`，支持 `USMART_HOME` 覆盖； - 默认注册全部 11 个工具（含 `place_order` / `modify_order`），装完即可下单； - 可选的服务端只读模式：写工具在 MCP 协议层完全不注册； - 写操作必须显式确认，且绝不自动重试； - 下单前可查询每手股数、最大可买卖数量和购买力； - 写操作在本地生成脱敏审计流水； - 查询类工具返回结构化结果，失败统一为错误信封； - 不提供行情服务，也不解析股票名称。 ## 环境要求 - Python 3.10 或更高版本； - [uv](https://docs.astral.sh/uv/getting-started/installation/)； - 独立的 uSmart SG OpenAPI 权限：使用 uSmart 账户在浏览器完成 OAuth2 授权即可，无需自行申请 App ID 或密钥。 PyPI 包不包含任何账户、Token 或密钥。 ## 安装 推荐用 `uvx` 固定版本运行： ```bash uvx --from "usmartsg-mcp==1.1.0" usmartsg-mcp ``` 也可以先安装再运行： ```bash pip install "usmartsg-mcp==1.1.0" usmartsg-mcp ``` 从源码安装：克隆本仓库后执行 ```bash cd usmartsg-mcp uv sync --extra dev uv run usmartsg-mcp ``` 该命令会保持运行并等待 MCP stdio 消息，属于正常行为，应由 MCP 客户端启动。 ## 快速开始 ### 1. 首次运行自动生成配置 **不需要手工创建配置文件**：首次启动时，如果 `~/.usmart/config.json` 不存在，服务会按内置 默认值自动生成一份；随后调用 `oauth_login` 在浏览器完成授权即可使用。 | 配置项 | 生产（默认） | 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` | 同左 | 生成后的目录： ```text ~/.usmart/ # macOS/Linux 建议权限 700 ├── config.json # 自动生成：固定 OAuth2 配置，可按需修改 ├── oauth_session.json # OAuth 授权成功后自动生成（600） ├── credentials.json # 可选：账户开启交易密码校验时创建，只写 tradePassword └── audit/ …