trading-mcp

Orderly Trading MCP

一个 MCP 服务，通过本地安装的 orderly CLI 为 AI 客户端提供 Orderly Network 交易访问能力。

私钥保存在操作系统密钥链中。MCP 进程永远不会接触私钥，也不会进行任何签名——它只会发现 CLI 的命令接口、验证参数，并将 CLI 作为子进程运行。

MCP client ⇄ stdio ⇄ orderly-trading-mcp ⇄ execFile ⇄ orderly CLI ⇄ Orderly API
                                                     ↳ OS keychain

要求

• Node.js >= 20
• 建议使用 orderly CLI v2.1.1+（v2.0.1 仍可使用）
  • v2.1.1 修复了 BID/ASK 市价单简写，将价格范围和最大数量相关拒绝归类为交易错误，并修复了 broker-status DEX 身份验证。
  • v2.1.0 新增了 Orderly Predict 命令、faucet-account，以及用于提供更丰富描述和支持可变参数的 longAbout/numArgs 架构字段。
  • 在 v2.0.1 上，MCP 会正常回退：predict 配置中没有 Predict 工具，不提供 faucet-account（请改用 faucet_usdc），描述较简短，可变参数使用硬编码回退方案。
• CLI 中已设置钱包/API 密钥（运行 orderly auth-list 可查看）

安装

# CLI (installs to ~/.local/bin)
curl -fsSL https://orderly.network/cli.sh | sh

# MCP server
npm install -g @orderly.network/trading-mcp
orderly-trading-mcp doctor

doctor 会列出找到的每个 CLI 候选项、选定的二进制文件、生效的配置/网络，以及密钥链中可见的账户。

客户端配置

可靠的配置方式是显式设置 ORDERLY_BIN。GUI 客户端启动时通常使用精简的 PATH，因此即使终端能找到 orderly，也可能无法找到 ~/.local/bin。如果密钥链中有多个账户，还应将 ORDERLY_MCP_ACCOUNT 设置为要作为默认账户的账户 ID。

Claude Code / Cursor（.mcp.json 或 .cursor/mcp.json）：

{
  "mcpServers": {
    "orderly-trading": {
      "command": "npx",
      "args": ["-y", "@orderly.network/trading-mcp"],
      "env": {
        "ORDERLY_BIN": "/Users/you/.local/bin/orderly"
      }
    }
  }
}

VS Code（.vscode/mcp.json）：

{
  "servers": {
    "orderly-trading": {
      "command": "npx",
      "args": ["-y", "@orderly.network/trading-mcp"],
      "env": { "ORDERLY_BIN": "/Users/you/.local/bin/orderly" }
    }
  }
}

OpenCode（opencode.json）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "orderly-trading": {
        "command": ["npx", "-y", "@orderly.network/trading-mcp"],
        "environment": {
          "ORDERLY_BIN": "/Users/you/.local/bin/orderly",
          "ORDERLY_MCP_TIMEOUT_MS": "180000"
        },
        "timeout": { "execution": 190000 }
      }
    }
  }
}

较旧版本的 OpenCode 使用已弃用的顶层 mcp.<name> 格式；其中的 timeout 是单个整数。上方的 mcp.servers 格式是当前格式。

Codex（.codex/config.toml）：

[mcp_servers.orderly-trading]
command = "npx"
args = ["-y", "@orderly.network/trading-mcp"]
env = { ORDERLY_BIN = "/Users/you/.local/bin/orderly" }

工具

默认的 core 配置会注册 15 个工具：

工具	类型	用途
auth_list	读取	已存储的账户（仅公开 ID）
account_balance	读取	代币持仓
positions_list	读取	持仓、账户价值、保证金
order_list	读取	当前委托
market_price	读取	标记价格/指数/24 小时统计数据
market_orderbook	读取	深度和最优买价/卖价
kline	读取	K 线
order_place	写入	下达永续合约委托
order_cancel	写入	取消一个委托
order_cancel_all	写入	取消所有委托
positions_close	写入	仅减仓市价平仓
leverage_get	读取	读取当前杠杆
leverage_set	写入	更改杠杆
orderly_commands / orderly_run	元数据	完整 CLI 覆盖范围

其他所有功能——算法/止盈止损委托、批量委托、Predict、交易、资金费率、历史记录、交易对、费率等级——都通过逃生舱口访问：

orderly_commands({ query: "algo" })
orderly_run({
  command: "algo-order-place",
  args: {
    symbol: "PERP_ETH_USDC", side: "SELL", algo_type: "TP_SL",
    quantity: 0.01, tp_trigger_price: 2500, account: "0x..."
  }
})

orderly_run 会应用通用策略：机密命令阻止列表、变更允许列表、读取命令允许列表、只读模式和主网门控。配置只控制专用工具范围；默认情况下，逃生舱口仍可访问所有允许的命令。设置 ORDERLY_MCP_STRICT_PROFILE=1 也可将 orderly_run 限制为所选配置的范围。由于它可能会修改数据，因此标注为非只读；通过它路由的读取操作可能会触发额外的客户端确认。列表查询请优先使用专用读取工具。

配置会为以下领域添加专用工具：

ORDERLY_MCP_PROFILE	工具
core（默认）	15
predict	core + 全部六个 Predict 工具，包括 predict_round（21）
algo	core + algo_order_place、algo_order_cancel、algo_order_list（18）
all	每个经过审查的读取命令 + 每个允许的交易变更命令（67）
full	all + withdraw、faucet_usdc、faucet_account（70；faucet_account 需要 CLI v2.1.0+）

安全模型

变量	默认值	作用
ORDERLY_BIN	auto	指定 CLI 路径；如果已设置但无效，则不会回退
ORDERLY_MCP_PROFILE	core	工具集（见上文）
ORDERLY_MCP_READ_ONLY	off	设置为 1 可禁用所有变更操作
ORDERLY_MCP_NETWORK	CLI config	默认网络覆盖值
ORDERLY_MCP_ACCOUNT	auto	调用未指定 account 时使用的默认账户 ID
ORDERLY_MCP_ALLOW_MAINNET	true	设置为 0 可阻止主网变更操作
ORDERLY_MCP_ALLOW_UNKNOWN_READS	off	设置为 1 可开放新的、未经审核的读取命令
ORDERLY_MCP_STRICT_PROFILE	off	设置为 1 后，orderly_run 只能访问所选配置集
ORDERLY_MCP_TIMEOUT_MS	30000	每次调用的超时时间
ORDERLY_MCP_MAX_OUTPUT	65536	每次调用返回的最大字符数
ORDERLY_MCP_DEBUG	off	将 argv/计时信息记录到 stderr

faucet_account --wait 最多可能需要 120 秒；使用前请提高 ORDERLY_MCP_TIMEOUT_MS（例如设置为 180000）。

设计规则：

• 密钥绝不会进入 MCP。 所有配置集（包括 orderly_run）都会阻止 wallet-create、wallet-import、 wallet-remove、wallet-logout、wallet-register、wallet-add-key、 wallet-revoke-key、auth-import、auth-logout、auth-cleanup、 broker-create 和 auth-export-key。auth-export-key 在 CLI 清单中属于只读命令，但会打印私钥，因此会被明确拒绝。
• 变更操作默认拒绝。 只有明确列入允许列表的交易命令可以执行变更。新的变更型 CLI 命令在审核前不会开放。
• 读取操作默认拒绝。 读取命令也列入允许列表，因此未经审核的新读取命令不会暴露敏感数据。设置 ORDERLY_MCP_ALLOW_UNKNOWN_READS=1 可选择不遵循此规则。
• 不使用 shell。 CLI 通过 argv 数组启动，因此十六进制账户 ID 和其他值无法注入 shell 语法。
• 不会卡住。 stdin 会关闭，因此交互式 CLI 提示会快速失败；每次调用都有超时时间。
• 变更操作会串行执行，因此并行工具调用不会重复提交。
• 先预览。 支持 --dry-run 的变更型工具会提供 dry_run 参数；工具说明会提示模型先预览再执行。
• 变更操作不会自动重试。

输出与错误

CLI 的紧凑 JSON 在大小合适时会原样传递。非 JSON 输出 （例如 No keys stored...）会以文本形式返回。如果响应超过 ORDERLY_MCP_MAX_OUTPUT，调用会返回明确错误，而不是返回被截断且无效的 JSON。返回逐行 success 标志的批量命令，只要有任意一行失败，就会报告为错误，并在消息中注明失败数量。

错误信息包含 CLI 的 stderr，以及根据错误类型给出的提示：

类型	处理方法
用法/验证	调用 orderly_commands 获取准确规范
API/交易拒绝	阅读错误消息；检查交易对、价格、数量、保证金和账户状态
身份验证	检查 auth_list / 使用 CLI 设置密钥
暂时性错误	稍后重试
多个账户	传入 account=<id> 或设置 ORDERLY_MCP_ACCOUNT

CLI 退出码分别为：2 表示用法错误，3 表示身份验证错误，4 表示交易拒绝，5 表示暂时性错误。MCP 会补充账户/网络上下文，且不会重试变更操作。

资源：orderly://schema、orderly://accounts、orderly://config、 orderly://guide。

开发

npm install
npm run typecheck     # tsc --noEmit
npm test              # builds dist/ + 59 unit/protocol tests
npm run build
npm run doctor
node dist/index.js tools   # print the registered tool list

测试使用隔离的模拟 CLI（test/fixtures/fake-orderly.mjs），因此不需要网络、密钥链或真实二进制文件。

CLI 架构在服务启动时加载一次。升级 CLI 或更改 ORDERLY_MCP_PROFILE / ORDERLY_BIN 后，请重启 MCP 服务。

发布

1. 更新 package.json、package-lock.json 和 server.json 中的所有版本号，然后提交。发布工作流会验证标签是否与 package.json 中的版本号匹配；注册表工作流会验证每个清单中的版本号是否一致。

2. 创建标签并推送：

   git tag v0.1.1
   git push origin master
   git push origin v0.1.1
   

3. .github/workflows/release.yaml 会运行类型检查、测试、构建和打包，然后发布到 npm，并附带来源证明（需要 NPM_TOKEN 密钥）。

4. .github/workflows/publish-registry.yaml 会验证 server.json，等待 npm 上出现该版本，然后使用 GitHub OIDC 将其发布到 MCP 注册表。

MCP 发布与 CLI 发布相互独立。CLI v2.1.1 已发布并推荐使用；v2.0.1 仍可通过回退机制正常工作。

此服务没有 Docker 镜像：它仅支持 stdio，与只读 MCP 不同。

（有意）不包含的内容

• 密钥、钱包、身份验证和经纪商管理工具。
• HTTP 传输。通过网络公开交易服务需要单独设计身份验证和威胁模型；目前仅支持 stdio。
• 自动下载 CLI。请显式安装；安装程序会验证发布校验和。