Orderly Trading MCP

MCP server that gives AI clients trading access to Orderly Network through the locally installed orderly CLI.

Private keys live in the OS keychain. The MCP process never sees them and never signs anything — it only discovers the CLI's command surface, validates arguments, and runs the CLI as a subprocess.

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

Requirements

• Node.js >= 20

• orderly CLI v2.0.1+ (v2.1.0+ recommended; it adds richer command metadata to orderly schema)

• A wallet/API key already set up in the CLI (orderly auth-list shows them)

Related MCP server: hyperliquid-mcp

Install

# 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 prints every CLI candidate it found, the selected binary, the effective profile/network, and the accounts visible in the keychain.

Client configuration

The reliable form sets ORDERLY_BIN explicitly. GUI clients often launch with a minimal PATH, so ~/.local/bin may not be visible even though your terminal finds orderly.

Claude Code / Cursor (.mcp.json or .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": {
    "orderly-trading": {
      "type": "local",
      "command": ["npx", "-y", "@orderly.network/trading-mcp"],
      "environment": { "ORDERLY_BIN": "/Users/you/.local/bin/orderly" },
      "enabled": true
    }
  }
}

Codex (.codex/config.toml):

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

Tools

The default core profile registers 14 tools:

Everything else — algo/TP-SL orders, batch orders, Predict, trades, funding, history, symbols, fee tiers — is reached through the escape hatch:

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 applies the same policy as the dedicated tools: secret-command blocklist, mutation allowlist, read-only mode and mainnet gate. Because it can mutate, it is annotated non-read-only; reads routed through it may trigger an extra client confirmation. Prefer the dedicated read tools for listings.

Profiles add dedicated tools for domains:

Safety model

faucet_account --wait can take up to 120 seconds; raise ORDERLY_MCP_TIMEOUT_MS (for example to 180000) before using it.

Design rules:

• Keys never enter the MCP. wallet-*, auth-import, auth-logout, auth-cleanup, broker-create and auth-export-key are blocked in every profile, including orderly_run. auth-export-key is read-only in the CLI manifest but prints a private key, so it is denied explicitly.

• Fail-closed mutations. Only an explicit allowlist of trading commands can mutate. A new mutating CLI command stays invisible until it is reviewed.

• No shell. The CLI is spawned with an argv array, so hex account IDs and other values cannot inject shell syntax.

• No hangs. stdin is closed, so interactive CLI prompts fail fast; every call has a timeout.

• Mutations are serialized, so parallel tool calls cannot double-submit.

• Preview first. Mutating tools that support --dry-run expose a dry_run argument; descriptions instruct the model to preview before executing.

• No automatic retries for mutations.

Output and errors

The CLI's compact JSON is passed through unchanged. Non-JSON output (for example No keys stored...) is returned as text. Errors include the CLI stderr and the exit-code meaning:

Resources: orderly://schema, orderly://accounts, orderly://config, orderly://guide.

Development

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

Tests use a hermetic fake CLI (test/fixtures/fake-orderly.mjs), so they do not need network, keychain or the real binary.

The CLI schema is loaded once at server startup. Restart the MCP server after upgrading the CLI or changing ORDERLY_MCP_PROFILE / ORDERLY_BIN.

Releasing

1. Bump version in package.json and every version in server.json, then commit. The registry workflow rejects mismatched versions.

2. Tag and push:

   git tag v0.2.0
   git push origin v0.2.0

3. .github/workflows/release.yaml runs typecheck, tests and build, then publishes to npm with provenance (NPM_TOKEN secret required).

4. .github/workflows/publish-registry.yaml waits for the npm version to appear, then publishes server.json to the MCP registry with GitHub OIDC.

There is no Docker image: this server is stdio-only, unlike the read-only MCP.

Not included (on purpose)

• Key, wallet, auth and broker management tools.

• HTTP transport. Exposing a trading server over the network needs its own authentication and threat model; stdio only for now.

• Automatic CLI download. Install it explicitly; the installer verifies the release checksum.